swagger 生成
根据 api 文件生成 swagger 文档，支持生成 json 和 yaml 格式的文档。
温馨提示
当前功能处于实验性阶段，要求：
- goctl 版本大于1.8.2
- 开启实验性功能
goctl env -w GOCTL_EXPERIMENTAL=on
指令
goctl api swagger -h
Generate swagger file from api
Usage:
goctl api swagger [flags]
Flags:
--api string api 文件
--dir string 输出目录
-h, --help help for swagger
--yaml 是否生成 yaml 格式
api 写法示例
- swagger 的标题，描述，版本，协议，联系人，许可证，host，basePath等信息全部在 api info 里面编写，可参考下文 api 示例
- 如果生成的 swagger 需要用 code-msg 包裹，可以在 info 描述中开启 wrapCodeMsg，设置为 true 字符串，生成的响应体示例和模型将会有 code-msg 包裹，格式模板如下:
{
"code": $code,
"msg": $msg,
"data": $responseData
}
示例
{
"code": 0,
"msg": "ok",
"data": {
"id": 1,
"name": "keson.an"
}
}
- 自定义业务错误码，当 wrapCodeMsg 开启后，可在 api info 中 通过 bizCodeEnumDescription 字段针对业务错误码进行枚举说明，方便生成 swagger 时将枚举信息渲染到 swagger 文档中，写法可参考下列示例。
- api 分组，对应 swagger 的 tags，可以在@server 中通过 tags 字段进行分组，tags 字段支持多个分组，多个分组用逗号隔开。
- 其他的 swagger 说明可参考下文示例
syntax = "v1"
info (
title: "演示 API" // 对应 swagger 的 title
description: "演示 api 生成 swagger 文件的 api 完整写法" // 对应 swagger 的 description
version: "v1" // 对应 swagger 的 version
termsOfService: "https://github.com/zeromicro/go-zero" // 对应 swagger 的 termsOfService
contactName: "keson.an" // 对应 swagger 的 contactName
contactURL: "https://github.com/zeromicro/go-zero" // 对应 swagger 的 contactURL
contactEmail: "example@gmail.com" // 对应 swagger 的 contactEmail
licenseName: "MIT" // 对应 swagger 的 licenseName
licenseURL: "https://github.com/zeromicro/go-zero" // 对应 swagger 的 licenseURL
consumes: "application/json" // 对应 swagger 的 consumes,不填默认为 application/json
produces: "application/json" // 对应 swagger 的 produces,不填默认为 application/json
schemes: "https" // 对应 swagger 的 schemes,不填默认为 https
host: "example.com" // 对应 swagger 的 host,不填默认为 127.0.0.1
basePath: "/v1" // 对应 swagger 的 basePath,不填默认为 /
wrapCodeMsg: "true" // 是否用 code-msg 通用响应体，如果开启，则以格式 {"code":0,"msg":"OK","data":$data} 包括响应体
bizCodeEnumDescription: "1001-未登录<br>1002-无权限操作" // 业务错误码枚举描述，json 格式,key 为业务错误码，value 为该错误码的描述，仅当 wrapCodeMsg 为 true 时生效
)
type (
QueryReq {
Id int `form:"id,range=[1:10000],example=10"`
Name string `form:"name,example=keson.an"`
Avatar string `form:"avatar,optional,example=https://example.com/avatar.png"`
}
QueryResp {
Id int `json:"id,example=10"`
Name string `json:"name,example=keson.an"`
}
PathQueryReq {
Id int `path:"id,range=[1:10000],example=10"`
Name string `form:"name,example=keson.an"`
}
PathQueryResp {
Id int `json:"id,example=10"`
Name string `json:"name,example=keson.an"`
}
)
@server (
tags: "query 演示" // 对应 swagger 的 tags,可以对 swagger 中的 api 进行分组
summary: "query 类型接口集合" // 对应 swagger 的 summary
prefix: v1
jwt: Auth
)
service Swagger {
@doc (
description: "query 接口"
)
@handler query
get /query (QueryReq) returns (QueryResp)
@doc (
description: "query path 中包含 id 字段接口"
)
@handler queryPath
get /query/:id (PathQueryReq) returns (PathQueryResp)
}
type (
FormReq {
Id int `form:"id,range=[1:10000],example=10"`
Name string `form:"name,example=keson.an"`
}
FormResp {
Id int `json:"id,example=10"`
Name string `json:"name,example=keson.an"`
}
)
@server (
tags: "form 表单 api 演示" // 对应 swagger 的 tags,可以对 swagger 中的 api 进行分组
summary: "form 表单类型接口集合" // 对应 swagger 的 summary
)
service Swagger {
@doc (
description: "form 接口"
)
@handler form
post /form (FormReq) returns (FormResp)
}
type (
JsonReq {
Id int `json:"id,range=[1:10000],example=10"`
Name string `json:"name,example=keson.an"`
Avatar string `json:"avatar,optional"`
Language string `json:"language,options=golang|java|python|typescript|rust"`
Gender string `json:"gender,default=male,options=male|female,example=male"`
}
JsonResp {
Id int `json:"id"`
Name string `json:"name"`
Avatar string `json:"avatar"`
Language string `json:"language"`
Gender string `json:"gender"`
}
ComplexJsonLevel2 {
// basic
Integer int `json:"integer,example=1"`
Number float64 `json:"number,example=1.1"`
Boolean bool `json:"boolean,options=true|false,example=true"`
String string `json:"string,example=some text"`
}
ComplexJsonLevel1 {
// basic
Integer int `json:"integer,example=1"`
Number float64 `json:"number,example=1.1"`
Boolean bool `json:"boolean,options=true|false,example=true"`
String string `json:"string,example=some text"`
// Object
Object ComplexJsonLevel2 `json:"object"`
PointerObject *ComplexJsonLevel2 `json:"pointerObject"`
}
ComplexJsonReq {
// basic
Integer int `json:"integer,example=1"`
Number float64 `json:"number,example=1.1"`
Boolean bool `json:"boolean,options=true|false,example=true"`
String string `json:"string,example=some text"`
// basic array
ArrayInteger []int `json:"arrayInteger"`
ArrayNumber []float64 `json:"arrayNumber"`
ArrayBoolean []bool `json:"arrayBoolean"`
ArrayString []string `json:"arrayString"`
// basic array array
ArrayArrayInteger [][]int `json:"arrayArrayInteger"`
ArrayArrayNumber [][]float64 `json:"arrayArrayNumber"`
ArrayArrayBoolean [][]bool `json:"arrayArrayBoolean"`
ArrayArrayString [][]string `json:"arrayArrayString"`
// basic map
MapInteger map[string]int `json:"mapInteger"`
MapNumber map[string]float64 `json:"mapNumber"`
MapBoolean map[string]bool `json:"mapBoolean"`
MapString map[string]string `json:"mapString"`
// basic map array
MapArrayInteger map[string][]int `json:"mapArrayInteger"`
MapArrayNumber map[string][]float64 `json:"mapArrayNumber"`
MapArrayBoolean map[string][]bool `json:"mapArrayBoolean"`
MapArrayString map[string][]string `json:"mapArrayString"`
// basic map map
MapMapInteger map[string]map[string]int `json:"mapMapInteger"`
MapMapNumber map[string]map[string]float64 `json:"mapMapNumber"`
MapMapBoolean map[string]map[string]bool `json:"mapMapBoolean"`
MapMapString map[string]map[string]string `json:"mapMapString"`
MapMapObject map[string]map[string]ComplexJsonLevel1 `json:"mapMapObject"`
MapMapPointerObject map[string]map[string]*ComplexJsonLevel1 `json:"mapMapPointerObject"`
// Object
Object ComplexJsonLevel1 `json:"object"`
PointerObject *ComplexJsonLevel1 `json:"pointerObject"`
// Object array
ArrayObject []ComplexJsonLevel1 `json:"arrayObject"`
ArrayPointerObject []*ComplexJsonLevel1 `json:"arrayPointerObject"`
// Object map
MapObject map[string]ComplexJsonLevel1 `json:"mapObject"`
MapPointerObject map[string]*ComplexJsonLevel1 `json:"mapPointerObject"`
// Object array array
ArrayArrayObject [][]ComplexJsonLevel1 `json:"arrayArrayObject"`
ArrayArrayPointerObject [][]*ComplexJsonLevel1 `json:"arrayArrayPointerObject"`
// Object array map
ArrayMapObject []map[string]ComplexJsonLevel1 `json:"arrayMapObject"`
ArrayMapPointerObject []map[string]*ComplexJsonLevel1 `json:"arrayMapPointerObject"`
// Object map array
MapArrayObject map[string][]ComplexJsonLevel1 `json:"mapArrayObject"`
MapArrayPointerObject map[string][]*ComplexJsonLevel1 `json:"mapArrayPointerObject"`
}
ComplexJsonResp {
// basic
Integer int `json:"integer,example=1"`
Number float64 `json:"number,example=1.1"`
Boolean bool `json:"boolean,options=true|false,example=true"`
String string `json:"string,example=some text"`
// basic array
ArrayInteger []int `json:"arrayInteger"`
ArrayNumber []float64 `json:"arrayNumber"`
ArrayBoolean []bool `json:"arrayBoolean"`
ArrayString []string `json:"arrayString"`
// basic array array
ArrayArrayInteger [][]int `json:"arrayArrayInteger"`
ArrayArrayNumber [][]float64 `json:"arrayArrayNumber"`
ArrayArrayBoolean [][]bool `json:"arrayArrayBoolean"`
ArrayArrayString [][]string `json:"arrayArrayString"`
// basic map
MapInteger map[string]int `json:"mapInteger"`
MapNumber map[string]float64 `json:"mapNumber"`
MapBoolean map[string]bool `json:"mapBoolean"`
MapString map[string]string `json:"mapString"`
// basic map array
MapArrayInteger map[string][]int `json:"mapArrayInteger"`
MapArrayNumber map[string][]float64 `json:"mapArrayNumber"`
MapArrayBoolean map[string][]bool `json:"mapArrayBoolean"`
MapArrayString map[string][]string `json:"mapArrayString"`
// basic map map
MapMapInteger map[string]map[string]int `json:"mapMapInteger"`
MapMapNumber map[string]map[string]float64 `json:"mapMapNumber"`
MapMapBoolean map[string]map[string]bool `json:"mapMapBoolean"`
MapMapString map[string]map[string]string `json:"mapMapString"`
MapMapObject map[string]map[string]ComplexJsonLevel1 `json:"mapMapObject"`
MapMapPointerObject map[string]map[string]*ComplexJsonLevel1 `json:"mapMapPointerObject"`
// Object
Object ComplexJsonLevel1 `json:"object"`
PointerObject *ComplexJsonLevel1 `json:"pointerObject"`
// Object array
ArrayObject []ComplexJsonLevel1 `json:"arrayObject"`
ArrayPointerObject []*ComplexJsonLevel1 `json:"arrayPointerObject"`
// Object map
MapObject map[string]ComplexJsonLevel1 `json:"mapObject"`
MapPointerObject map[string]*ComplexJsonLevel1 `json:"mapPointerObject"`
// Object array array
ArrayArrayObject [][]ComplexJsonLevel1 `json:"arrayArrayObject"`
ArrayArrayPointerObject [][]*ComplexJsonLevel1 `json:"arrayArrayPointerObject"`
// Object array map
ArrayMapObject []map[string]ComplexJsonLevel1 `json:"arrayMapObject"`
ArrayMapPointerObject []map[string]*ComplexJsonLevel1 `json:"arrayMapPointerObject"`
// Object map array
MapArrayObject map[string][]ComplexJsonLevel1 `json:"mapArrayObject"`
MapArrayPointerObject map[string][]*ComplexJsonLevel1 `json:"mapArrayPointerObject"`
}
)
@server (
tags: "post json api 演示" // 对应 swagger 的 tags,可以对 swagger 中的 api 进行分组
summary: "json 请求类型接口集合" // 对应 swagger 的 summary
)
service Swagger {
@doc (
description: "简单的 json 请求体接口"
)
@handler jsonSimple
post /json/simple (JsonReq) returns (JsonResp)
@doc (
description: "复杂的 json 请求体接口"
)
@handler jsonComplex
post /json/complex (ComplexJsonReq) returns (ComplexJsonResp)
}