简体中文

English

简体中文

English

主题

CodeGen 使用说明 ​

CodeGen 是 Swagger.io 的一个开源项目，符合 OpenAPI SPEC 的 API 文档可以通过 CodeGen 生成对应的 SDK 源码和接口文档。本文档主要介绍如何编写符合 OAS v2 的文档，检测语法错误，生成 SDK 以及测试 SDK。

整体使用流程介绍 ​

  1. 确定接口功能
  2. 编辑符合 OpenApi Spec v2 的 API 文档（支持 yaml 或 json 格式）
  3. 检测 API 文档语法错误
  4. 使用提供的工具生成 SDK
  5. 测试 SDK
  6. 提供 SDK 给业务组

接下来介绍 step2，3，4，5 的工作流程。

编辑，检测 API 文档 ​

虽然 CodeGen 支持到 OAS3，但是不够稳定，我们目前只支持 v2 版本，下面的示例是我们的一个真实 App Server 文档，是官方文档的一部分常用用法，当你需要更丰富的用法，请移步查看官方文档 OAS2 SPEC。

示例中包含了 POST、GET、PUT、DELETE 请求类型，常见的 request 参数：body，query，header，path，formData 类型等，response 参数。 提供用户登录，用户资料更新获取，show 资料 文件上传，获取，删除功能：

你需要 在线文档编辑器 ，提供实时报错，和一些智能提示。

示例标签说明 ​

  • swagger ： 必填项，目前我们只支持到 2.0
  • info ： 必填项，提供关于 API 的 metadata
  • host ： 域名
  • consumes ：API request 的 MIME type，全局定义，也可以在每个 API 上覆盖全局定义
  • produces ：API response 的 MIME type，全局定义，也可以在每个 API 上覆盖全局定义
  • tags ：定义不同的标签，生成对应的 API 类 比如 UserAPI，ShowsAPI
  • schemes ：API 支持的协议，如 http，https
  • paths ： 每个 API 请求的具体描述
  • definitions ： 可复用的对象定义，比如几个接口返回相同的数据类型，那么可以用 ref 的方式引用 definitions 中定义的对象

示例 ​

完整示例见 链接

swagger: "2.0" #必填项，目前我们只支持到 2.0
info: # 必填项，提供关于 API 的 metadata
  description: "AppServer openApi"
  version: "1.0.0"
  title: "appServer"
  termsOfService: "http://swagger.io/terms/"
  contact:
    email: "bing.he@ihandysoft"
  license:
    name: "Apache 2.0"
    url: "http://dev-colorphone-service.appcloudbox.net"
host: "dev-colorphone-service.appcloudbox.net"  # 域名

consumes: # API 消费的 MIME type，全局定义，也可以在每个 API 上覆盖定义
  - "application/json"
produces: # API 生产的 MIME type，全局定义，也可以在每个 API 上覆盖定义
  - "application/json"
tags: # 标签 定义不同的标签，生成对应的 API 类 比如 UserAPI,ShowsAPI
- name: "User"
  description: "Everything about userlogin"
  externalDocs:
    description: "Find out more"
    url: "http://swagger.io"
- name: "Shows"
  description: "shows"
  externalDocs:
    description: "shows"
    url: "http://swagger.io"

schemes: # API 支持的协议
- "http"

paths: # 必填项
  /user/login: # uri 路径
    post: # 请求的类型 ，其他还有 get，put，delete，options，head，patch
      tags: # 标签，引用上面 tags 定义的 User 标签
      - "User"
      summary: "UserLogin" # 生成的文档描述用到
      description: "user login" # 生成的文档描述用到
      operationId: "userlogin" # 生成的 方法名，如 new UserAPI().userlogin()

      parameters: # 请求参数
      - in: "header" # 参数类型 header，其他还有 query，header，path，formData
        name: "X-ColorPhone-Signature"
        required: true # 是否必须
        description: Signature
        type: string # 参数数据类型

      - in: "body" # 参数类型 body
        name: "LoginRequest" # 请求参数名称，建议和请求数据类名保持一致，请避免不要和 json 字符串中任何 key 相同，否则生成的 class name 和 member name 相同
        description: "user login ,only support wechat"  # 参数描述，生成的文档用的到
        required: true
        schema:  # 类型约束 ，这个是引用数据类型，对象定义在 definitions 标签下
          $ref: "#/definitions/LoginRequest"
      responses: # 响应定义
        200: # 正确响应码
          description: "ok" # 文档描述
          schema: # 类型约束，引用数据类型，对象定义在 definitions
            $ref: "#/definitions/LoginResponse"

        405: #错误响应码
          description: "Invalid input"

  /user/{user_id}/profile:
    put:
      tags:
      - "User"
      summary: "UserProfile"
      description: "UserProfile"
      operationId: "putUserProfile"
      consumes: # 因为需要上传文件，用该标签覆盖全局的 consumes
        - multipart/form-data
      parameters:
      - in: "header"
        name: "X-ColorPhone-Session-Token"
        type: string
        description: Token
      - in: "header"
        name: "X-ColorPhone-Signature"
        type: string
        description: Signature
      - name: user_id
        in : path
        required: true
        type: string
      - in: "formData"
        name: "name"
        description: "user login ,only support wechat"
        required: true
        type: string
      - in: "formData"
        name: "gender"
        description: "user login ,only support wechat"
        required: true
        type: string
      - in: "formData"
        name: "birthday"
        description: "user login ,only support wechat"
        required: true
        type: string
      - in: "formData"
        name: "signature"
        description: "user login ,only support wechat"
        required: true
        type: string
      - in: "formData"
        name: "head_image"
        description: "user login ,only support wechat"
        required: true
        type: file # 参数数据类型 file
      responses:
        200:
          description: "ok"
          schema:
            type: string
            example: "ok"
        405:
          description: "Invalid input"

definitions:  # 对象定义
  LoginRequest:
    type: object # 是对象类型
    properties:
      login_type:
        type: integer # int 类型
        example: 1
      login_info:
        type: object # 对象，子标签 additionalProperties: {}表明这是字典类型
        example: {
          "wechat_code":"XXXXX"
        }

        additionalProperties: {} # key ：string value：object
  LoginResponse:
    type: object
    properties:
      token:
        type: string
        example: "h86s5f65fd2h"
      user_info:
        $ref: '#/definitions/UserInfo'   # 对象也可以嵌套

  UserInfo:
    type: object
    properties:
      user_id:
        type: string
        example: "UUAGBMG2IVCLP"
      name:
        type: string
        example: "iHandy"
      head_image_url:
        type: string
        example: "url"
      gender:
        type: string
        example: "man"
      birthday:
        type: string
        example: "2019-02-09"
      signature:
        type: string
        example: "iHandy is best!!!"
  externalDocs:
  description: "Find out more about Swagger"
  url: "http://swagger.io"

生成 SDK ​

请通过我们的 sdktool 生成 SDK。sdktool 工具可用来对符合 OAS2 的 API 文档生成指定语言的 SDK，目前支持 C#

安装 sdktool ​

确保 python3 >= 3.7

下载 安装包 后安装

pip3 install sdktool-xxx.tar.gz

校验 API 文档 ​

除了上面提到的工具外，sdktool 工具也支持检验 API 文档是否符合 OpenAPI SPEC，检验命令如下：

bash
sdktool validate -s <path_of_api_file>

其中 path_of_api_file 是 API 文档路径，API 文档需以 YAML 或 JSON 格式给出。

生成 SDK 库 ​

sdktool 工具可用来生成指定语言的 SDK，命令如下：

bash
sdktool generate -l <language> -s <path_of_api_file> -o <path_of_option_file>

其中：

language 为目标 SDK 的编程语言，如需要生成 Unity 的 SDK，请指定为 csharp。

path_of_api_file 是 API 文档路径，API 文档需以 YAML 或 JSON 格式给出。

path_of_option_file 为生成的 SDK 配置文件路径，配置文件以 JSON 格式给出。对于 Unity SDK，一般需要的配置有：

  • packageName 生成的 SDK 包名
  • packageVersion SDK 版本号
  • targetFramework SDK 的目标 .NET 框架版本，支持的有 v3.5, v4.0, v4.5, v5.0 和 uwp。默认是 v4.5。 当设置为 v5.0 时，不会生成测试代码，会影响 SDK 的测试。
  • netCoreProjectFile 是否生成 .NET Core 格式的 project，默认是 false。 只有当 targetFramework 为 v5.0 时，该选项才可设置为 true，生成的代码才能够通过 dotnet build 构建成功。

一个例子如下：

json
{
  "packageName": "ColorphoneClient",
  "packageVersion": "1.0.0",
  "targetFramework": "v4.5",
  "netCoreProjectFile": false
}

csharp 支持的更多 option 可以参考 链接

测试 SDK ​

前提条件 ​

  • SDK 无错误
  • SDK 请求的服务存在

如果你是使用本文提供的示例文档生成的 SDK，是可以忽略 Mock Server 部分直接测试的，测试所需参数如下：

uid: ”UUAJBTPEAP3CQ“
xColorPhoneSessionToken: ”CNAJBTPFCU36NK“
xColorPhoneSignature: “12345678,87654321”

具体测试流程见：测试流程文档链接

一些建议 ​

  • 建议文档中每一个 API 都包含 operationId 配置，生成的 SDK 中的接口会以该字段命名
  • type 支持的数据类型有限，可以用 format 支持更多数据类型
  • 如果 request body 是 json 格式字符串，parameters 标签下 body 请求参数的 name 不要和 json 字符串中任何 key 相同，否则生成的 class name 和 member name 相同
  • required 标签很重要，会影响到 SDK 参数校验
  • 同一个 paths 下可以放置多个请求类型，如 put，get，delete

京ICP备19011570号-2

版权所有 © 2019-2025 BytePower