CodeGen 使用说明
# CodeGen 使用说明
CodeGen 是 Swagger.io 的一个开源项目,符合 OpenAPI SPEC 的 API 文档可以通过 CodeGen 生成对应的 SDK 源码和接口文档。本文档主要介绍如何编写符合 OAS v2 的文档,检测语法错误,生成 SDK 以及测试 SDK。
# 整体使用流程介绍
- 确定接口功能
- 编辑符合 OpenApi Spec v2 的 API 文档(支持 yaml 或 json 格式)
- 检测 API 文档语法错误
- 使用提供的工具生成 SDK
- 测试 SDK
- 提供 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