Swagger API 生成器

写在前面

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

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

命令格式

ng g ng-alain:sta --name=<Swagger name> --url=<远程URL地址> --filePath=<本地Swagger.json文件> --output=<输出路径>

参数名	默认	描述
`name`	`sta`	Swagger 项目名称
`url`	-	远程 Swagger.json 文件，`url` 与 `filePath` 必须二选一
`filePath`	-	本地 Swagger.json 文件路径，`url` 与 `filePath` 必须二选一
`output`	`src/app/${name}`	输出目录
`responseDataField`	-	Response 的真实数据字段
`modelTypePrefix`	-	数据契约名称前缀
`httpClientType`	`delon`	HttpClient 请求方式，1. `delon` 使用 `@delon/theme` 的 `_HttpClient`，2. `angular` 使用 `HttpClient`
`generateApiOptions`	-	swagger-typescript-api options
`tagsMapping`	-	Swagger标签映射字典，当标签为中文时，可以指定用于转换成更加符合规范 Service 名

使用配置文件

在项目根目录增加 sta.json：

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

执行：

ng g ng-alain:sta

常见问题

路径与Service的关联

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

不符合预期的名称

默认情况下，会根据 operationId 项目来处理，否则会自动根据 path 与 method 组合。为了保持与后端的统一项，建议开启 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" 来解决。