1.0.2 • Published 2 years ago
@open-sdnx/generator v1.0.2
目前我们公司后端工程生成出来的openapi文档和swagger官网公开的OpenApi规范有很大不同,因此此生成工具并不能做到通用
以下大致梳理一下我们公司后端用某版本swagger生成出来的openapi文档中的关键信息:
{
info: {
version: "1.0", // 这份文档的版本
title: "所有接口" // 这份文档的标题
},
host: "192.168.2.25:8070", // ip+端口,称之为主机地址
tags: [ // tag名词解释表,往后看,你会明白有什么用
{
name: "产品类型管理", // 标签名
description: "Account Product Controller" // 标签描述
},
...
],
paths: [ // 包含了所有接口的描述的一个列表,也是最重要的一个字段
"/account/accountConfigure/add": {
"post": { // 请求方式 http method
tags: [
"产品类型管理" // 用tag可以对接口进行归类
],
summary: "新增账户配置信息", // 接口的简短描述
parameters: [ // 此接口的参数列表
{
in: "body", // 参数放置位置 body | path | query,规范上并没有指出body这个值,并且不止这三个值
name: "addAccountConfigDTO",
description: "addAccountConfigDTO",
required: true, // 此参数是否必传
schema: { // 指定了此参数的类型约束
$ref: "#/definitions/AddAccountConfigDTO" // 引用下面definitions表下中的对象到这里
}
}
],
responses: {
"200": {
description: "OK",
schema: { // 指定了此响应结果的类型约束
$ref: "#/definitions/返回参数"
}
},
"404": {
description: "Not Found"
}
}
}
},
// 再看一个接口例子
"get": {
parameters: [
{
name: "productNo",
in: "query", // 意思是要把这个参数追加到url中
description: "产品编号",
required: false,
type: "string" // 参数类型,基本数据类型就这样指定,和上面schema(复杂数据类型)不同
}
],
...
}
],
definitions: {
AddAccountConfigDTO: {
type: "object", // object | array
required: [ // 必须要有的属性
"a",
"b"
],
properties: {
a: {
type: "string", // 此属性的类型
description: "字段a", // 描述
enum: [ // 枚举值列表
"YES",
"NO"
]
},
b: {
type: "number",
description: "字段b"
},
c: {
description: "字段c,我是一个复杂数据类型的字段",
$ref: "#/definitions/xxx" // 它引用了另一个类型约束
}
}
},
返回参数: {
...
}
}
}
有了这些信息,便可以实现一个非通用的代码生成器了