CodeGen 使用说明

# 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 (opens new window)

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

你需要 在线文档编辑器 (opens new window) ,提供实时报错,和一些智能提示。

# 示例标签说明

  • 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,检验命令如下:

sdktool validate -s <path_of_api_file>

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

# 生成 SDK 库

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

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 构建成功。

一个例子如下:

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

csharp 支持的更多 option 可以参考 链接 (opens new window)

# 测试 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
上次更新: 2020/1/4 13:27:48