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。
示例中包含了 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，检验命令如下：
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 可以参考 链接
# 测试 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