BytePower

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