服务配置

快速开始

最简单的服务配置只需要三个基础参数：

{
  "code": "product",
  "source": "https://www.apisorcery.com/demo-api/swagger-json",
  "version": 3
}

这三个参数就足以让你开始使用 AutoAPI！

参数说明

基础参数（必需）

以下三个参数是配置服务的最小集合，也是最重要的参数：

code

• 类型：string
• 必填

服务的编号，由用户自行定义。

注：生成 API 时,会按应用的输出目录和服务的编号来生成目录，服务的所有 API 文件都放在这个目录下。 如应用的输入目录为 ./src/api/auto,服务编号为product,则最终的生成目录为 ./src/api/auto/product

source

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

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

version

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

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

---

高级参数（可选）

以下参数用于更精细的控制和定制，可以根据实际需求选择性配置：

enabled

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

当前服务是否启用，禁用后生成 API 时排除当前服务。当前应用下的其他服务不受影响。

returnLevel

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

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

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

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

returnSecondField

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

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

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

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

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

此时 returnSecondField 可指定为 data

baseStrategy

• 类型：string
• 默认值：'once'
• 可选值：'once'｜'always'

生成Base文件的策略。

• 'once': 只在文件不存在时生成；如果已存在则保留不覆盖（默认）
• 'always': 每次生成都会覆盖

httpClientStrategy

• 类型：string
• 默认值：'once'
• 可选值：'once'｜'always'|'none'

生成HttpClient文件夹的策略。

• 'once': 只在文件不存在时生成；如果已存在则保留不覆盖（默认）
• 'always': 每次生成都会覆盖
• 'none': 不生成

tagNameMap

• 类型：object

Swagger Tag 名称到生成代码中类名前缀的映射表。

为什么重要：每个 Swagger Tag 会成为生成的 API 客户端中的一个类。 类名由 Tag 名称衍生而来，因此必须符合标识符命名规则 — 只有 ASCII 字母、数字和下划线是合法的。含非 ASCII 字符（汉字、日文、阿拉伯文等） 的 Tag 名称会产生无法编译的类名。

Tag 命名规则

含非 ASCII 字符的 Tag 必须通过 tagNameMap 配置映射。 若未配置，AutoAPI 会尝试从该 Tag 下的 API 路径推断类名。推断成功时会输出警告并继续生成； 推断失败时则直接使用原始 Tag 名作为类名 —— 生成的代码将无法编译。

示例：

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

生成的 API 文档如下：