Swagger API 生成器

写在前面

若后端API文档是由 Swagger 来描述,将可以通过以下命令来生成一组完整的 API 代码:

ng g ng-yunzai:sta --url=https://petstore3.swagger.io/api/v3/openapi.json 

命令格式

ng g ng-yunzai:sta --name=<Swagger name> --url=<远程URL地址> --filePath=<本地Swagger.json文件> --output=<输出路径>
参数名默认描述
namestaSwagger 项目名称
url-远程 Swagger.json 文件,urlfilePath 必须二选一
filePath-本地 Swagger.json 文件路径,urlfilePath 必须二选一
outputsrc/app/${name}输出目录
responseDataField-Response 的真实数据字段
modelTypePrefix-数据契约名称前缀
httpClientTypeyelonHttpClient 请求方式,1. yelon 使用 @yelon/theme_HttpClient,2. angular 使用 HttpClient
generateApiOptions-swagger-typescript-api options
tagsMapping-Swagger标签映射字典,当标签为中文时,可以指定用于转换成更加符合规范 Service 名

使用配置文件

在项目根目录增加 sta.json

{
  "$schema": "./node_modules/ng-yunzai/sta/schema.json",
  "filePath": "swagger.json",
  "tagsMapping": {
    "部门": "Dept"
  }
}

执行:

ng g ng-yunzai:sta

常见问题

路径与Service的关联

默认会将每个 path 第一个 tags 合并为一个 Service,请尽可能使用 [a-zA-Z][-_a-zA-Z]+ 来描述 tag

不符合预期的名称

默认情况下,会根据 operationId 项目来处理,否则会自动根据 pathmethod 组合。为了保持与后端的统一项,建议开启 operationId 支持,以下是几种语言开启方法:

.NET CORE

// Swashbuckle
services.AddSwaggerGen(c =>
{
  c.CustomOperationIds(e =>
  {
    var name = e.ActionDescriptor.RouteValues["action"] ?? "";
    return name[0].ToString().ToLower() + name.Substring(1);
  });
}

JAVA

参考 Configuring the output of operationId in a Swagger 2.0 spec.

全局Response

当所有 path 有固定输出格式时,比如成功、异常都有统一格式时都返回时:

{
  "status": 200,
  "error": "Error Message",
  "result": {}
}

若是通过拦截器来处理异常消息时,订阅时只需要始终获取 result 字段数据时,可以通过指定 --responseDataField="result" 来解决。

Loading...