AutoAPI

Appearance

服务配置 ​

示例 ​

json
{
  "name": "product",
  "token": "682db637-0f31-4847-9cdf-3232432dfsfd",
  "source": "http://localhost:9002/swagger-json",
  "version": 3,
  "enabled": true,
  "returnLevel": "second",
  "returnSecondField": "data",
  "tagNameMap": {
    "用户管理": "User",
    "用户认证": "Auth",
    "应用管理": "Application"
  }
}

参数说明 ​

name ​

  • 类型：string

服务的名称，可在控制台配置。

token ​

  • 类型：string

服务的令牌，在控制台创建服务后自动生成。

source ​

  • 类型：string
  • 支持在线文件，如https://***/swagger.json
  • 支持本地文件(相对路径)，如./**/swagger.json

Swagger 的地址，同时支持本地文件和在线文件。

version ​

  • 类型：number
  • 可选值：2｜3

Swagger 的版本，目前支持 Swagger/AutoAPI 2.x/3.x。

enabled ​

  • 类型：boolean
  • 默认值：true
  • 可选值：true｜false

当前服务是否启用，禁用后生成 API 时排除当前服务。

returnLevel ​

  • 类型：string
  • 默认值：'second'
  • 可选值：'second'｜'first'

生成 API 应答报文的结构层级。 由于接口在处理时，通常会返回如下结构：

json
{
  "status" : 0,
  "message" : "OK",
  "data" : {
    xxx:xxx
  }
}

第一层结构往往通过接口拦截器统一处理（如错误提示等），实际上只需要处理第二次结构即可,所以此参数默认为second。

returnSecondField ​

  • 类型：string
  • 仅当 returnLevel为 second 时有效

生成 API 应答报文的第二层结构时指定的字段。

由于用户返回的结果并不统一，所以需要指定此字段。

示例 当接口返回如下结构时：

json
{
  "status" : 0,
  "message" : "OK",
  "data" : {
    xxx:xxx
  }
}

此时 returnSecondField 可指定为 data

tagNameMap ​

  • 类型：object

Swagger 分组标识 Tag 的映射。

由于用户在 Tag 中常使用汉字，这对生成 API 文件时并不友好，所以此处需要用户指定，以便生成可读性更好的 API 文件。

示例：

json
{
  "tagNameMap": {
    "用户管理": "User",
    "用户认证": "Auth",
    "应用管理": "Application"
  }
}

生成的 API 文档如下：

alt text