swagger文档生成 : 增加输入配置的格式化
This commit is contained in:
parent
091d0b7a0f
commit
114b5db641
@ -51,8 +51,8 @@ type SwaggerPathConfig struct {
|
|||||||
Consumes []string `json:"consumes"` // 请求方式, application/json等
|
Consumes []string `json:"consumes"` // 请求方式, application/json等
|
||||||
Tags []string `json:"tags"` // 接口标签
|
Tags []string `json:"tags"` // 接口标签
|
||||||
Summary string `json:"summary"` // 接口摘要
|
Summary string `json:"summary"` // 接口摘要
|
||||||
Parameters []SwaggerPathConfigParameter `json:"parameters"` // 参数列表
|
Parameters []*SwaggerPathConfigParameter `json:"parameters"` // 参数列表
|
||||||
Response map[string]SwaggerPathConfigResponse `json:"response"` // code码 => 响应描述
|
Response map[string]*SwaggerPathConfigResponse `json:"response"` // code码 => 响应描述
|
||||||
}
|
}
|
||||||
|
|
||||||
// SwaggerPathConfigParameter ...
|
// SwaggerPathConfigParameter ...
|
||||||
@ -65,7 +65,7 @@ type SwaggerPathConfigParameter struct {
|
|||||||
Description string `json:"description"` // 描述
|
Description string `json:"description"` // 描述
|
||||||
Name string `json:"name"` // 参数名称
|
Name string `json:"name"` // 参数名称
|
||||||
In string `json:"in"` // 参数位置
|
In string `json:"in"` // 参数位置
|
||||||
Required bool `json:"required"` // 是都必传
|
Required bool `json:"required"` // 是否必传
|
||||||
Schema map[string]string `json:"schema"` // 参数schema
|
Schema map[string]string `json:"schema"` // 参数schema
|
||||||
}
|
}
|
||||||
|
|
||||||
@ -110,6 +110,62 @@ type Swagger struct {
|
|||||||
Swagger string `json:"swagger"` // swagger版本 - 2.0
|
Swagger string `json:"swagger"` // swagger版本 - 2.0
|
||||||
Host string `json:"host"` // 服务域名
|
Host string `json:"host"` // 服务域名
|
||||||
BasePath string `json:"basePath"` // 基础path
|
BasePath string `json:"basePath"` // 基础path
|
||||||
|
Info Info `json:"info"` // 文档描述信息
|
||||||
Paths map[string]map[string]SwaggerPathConfig `json:"paths"` // 接口列表 : 接口 => 请求方法 => 请求配置
|
Paths map[string]map[string]SwaggerPathConfig `json:"paths"` // 接口列表 : 接口 => 请求方法 => 请求配置
|
||||||
Definitions map[string]SwaggerDefinition `json:"definitions"` // 数据定义
|
Definitions map[string]SwaggerDefinition `json:"definitions"` // 数据定义
|
||||||
}
|
}
|
||||||
|
|
||||||
|
// SwaggerInput ...
|
||||||
|
//
|
||||||
|
// Author : go_developer@163.com<白茶清欢>
|
||||||
|
//
|
||||||
|
// Date : 10:18 2024/4/22
|
||||||
|
type SwaggerInput struct {
|
||||||
|
Schemes []string `json:"schemes"` // 协议
|
||||||
|
Swagger string `json:"swagger"` // swagger版本 - 2.0
|
||||||
|
Host string `json:"host"` // 服务域名
|
||||||
|
BasePath string `json:"basePath"` // 基础path
|
||||||
|
Info Info `json:"info"` // 文档描述信息
|
||||||
|
PathConfigList []*SwaggerPathInput `json:"path_config_list"` // 接口配置列表
|
||||||
|
}
|
||||||
|
|
||||||
|
// SwaggerPathInput 接口配置
|
||||||
|
//
|
||||||
|
// Author : go_developer@163.com<白茶清欢>
|
||||||
|
//
|
||||||
|
// Date : 10:20 2024/4/22
|
||||||
|
type SwaggerPathInput struct {
|
||||||
|
Uri string `json:"uri"` // 接口
|
||||||
|
Method string `json:"method"` // 请求方法
|
||||||
|
ContentType string `json:"content_type"` // 请求方式
|
||||||
|
Summary string `json:"summary"` // 摘要
|
||||||
|
Description string `json:"description"` // 描述
|
||||||
|
TagList []string `json:"tag_list"` // 标签列表
|
||||||
|
ParameterList []*SwaggerParameterInput `json:"parameter_list"` // 参数列表
|
||||||
|
ResponseList []*SwaggerResponseInput `json:"response_list"` // 响应数据
|
||||||
|
}
|
||||||
|
|
||||||
|
// SwaggerParameterInput ...
|
||||||
|
//
|
||||||
|
// Author : go_developer@163.com<白茶清欢>
|
||||||
|
//
|
||||||
|
// Date : 10:25 2024/4/22
|
||||||
|
type SwaggerParameterInput struct {
|
||||||
|
Type string `json:"type"` // 类型
|
||||||
|
Description string `json:"description"` // 描述
|
||||||
|
Name string `json:"name"` // 参数名称
|
||||||
|
In string `json:"in"` // 参数位置
|
||||||
|
Required bool `json:"required"` // 是否必传
|
||||||
|
}
|
||||||
|
|
||||||
|
// SwaggerResponseInput 响应数据
|
||||||
|
//
|
||||||
|
// Author : go_developer@163.com<白茶清欢>
|
||||||
|
//
|
||||||
|
// Date : 10:49 2024/4/22
|
||||||
|
type SwaggerResponseInput struct {
|
||||||
|
Type string `json:"type"` // 类型
|
||||||
|
Description string `json:"description"` // 描述
|
||||||
|
Field string `json:"field"` // 字段名
|
||||||
|
IsRequired bool `json:"is_required"` // 是否一定存在
|
||||||
|
}
|
||||||
|
|||||||
15
go.mod
15
go.mod
@ -1,3 +1,18 @@
|
|||||||
module git.zhangdeman.cn/gateway/api-doc
|
module git.zhangdeman.cn/gateway/api-doc
|
||||||
|
|
||||||
go 1.22.2
|
go 1.22.2
|
||||||
|
|
||||||
|
require (
|
||||||
|
git.zhangdeman.cn/zhangdeman/consts v0.0.0-20240422030654-fc4470a2cebc // indirect
|
||||||
|
git.zhangdeman.cn/zhangdeman/easymap v0.0.0-20240311030808-e2a2e6a3c211 // indirect
|
||||||
|
git.zhangdeman.cn/zhangdeman/serialize v0.0.0-20240325080031-1f58204e8687 // indirect
|
||||||
|
git.zhangdeman.cn/zhangdeman/util v0.0.0-20231227095334-7eb5cdbf9253 // indirect
|
||||||
|
git.zhangdeman.cn/zhangdeman/wrapper v0.0.0-20240422034417-8c922be06d95 // indirect
|
||||||
|
github.com/BurntSushi/toml v1.3.2 // indirect
|
||||||
|
github.com/axgle/mahonia v0.0.0-20180208002826-3358181d7394 // indirect
|
||||||
|
github.com/go-ini/ini v1.67.0 // indirect
|
||||||
|
github.com/mitchellh/go-homedir v1.1.0 // indirect
|
||||||
|
github.com/mozillazg/go-pinyin v0.20.0 // indirect
|
||||||
|
github.com/spaolacci/murmur3 v1.1.0 // indirect
|
||||||
|
gopkg.in/yaml.v3 v3.0.1 // indirect
|
||||||
|
)
|
||||||
|
|||||||
29
go.sum
Normal file
29
go.sum
Normal file
@ -0,0 +1,29 @@
|
|||||||
|
git.zhangdeman.cn/zhangdeman/consts v0.0.0-20240419080457-9d9562469008 h1:6z99+X/B/G9sCZ+aTLYGWk3YLVVODzevA4wjWj9jvq0=
|
||||||
|
git.zhangdeman.cn/zhangdeman/consts v0.0.0-20240419080457-9d9562469008/go.mod h1:IXXaZkb7vGzGnGM5RRWrASAuwrVSNxuoe0DmeXx5g6k=
|
||||||
|
git.zhangdeman.cn/zhangdeman/consts v0.0.0-20240422030654-fc4470a2cebc h1:1fgPDwrLyvRP5A5PAoog3RtRQZ6c7JFtl+ZJmFEqyQQ=
|
||||||
|
git.zhangdeman.cn/zhangdeman/consts v0.0.0-20240422030654-fc4470a2cebc/go.mod h1:IXXaZkb7vGzGnGM5RRWrASAuwrVSNxuoe0DmeXx5g6k=
|
||||||
|
git.zhangdeman.cn/zhangdeman/easymap v0.0.0-20240311030808-e2a2e6a3c211 h1:I/wOsRpCSRkU9vo1u703slQsmK0wnNeZzsWQOGtIAG0=
|
||||||
|
git.zhangdeman.cn/zhangdeman/easymap v0.0.0-20240311030808-e2a2e6a3c211/go.mod h1:SrtvrQRdzt+8KfYzvosH++gWxo2ShPTzR1m3VQ6uX7U=
|
||||||
|
git.zhangdeman.cn/zhangdeman/serialize v0.0.0-20240325080031-1f58204e8687 h1:uQcGqdzi4UdpZlp4f4FUPeBqoygP58pEKJkmN3ROsE0=
|
||||||
|
git.zhangdeman.cn/zhangdeman/serialize v0.0.0-20240325080031-1f58204e8687/go.mod h1:gf7SW2TXATgux8pfdFedMkXWv2515OtIIM/5c4atkFw=
|
||||||
|
git.zhangdeman.cn/zhangdeman/util v0.0.0-20231227095334-7eb5cdbf9253 h1:GO3oZa5a2sqwAzGcLDJtQzmshSWRmoP7IDS8bwFqvC4=
|
||||||
|
git.zhangdeman.cn/zhangdeman/util v0.0.0-20231227095334-7eb5cdbf9253/go.mod h1:VpPjBlwz8U+OxZuxzHQBv1aEEZ3pStH6bZvT21ADEbI=
|
||||||
|
git.zhangdeman.cn/zhangdeman/wrapper v0.0.0-20240419103925-ee726ea6bcff h1:nYj5DQ6k5i83eFMkocgBKe3NNCXM2aOoJ4NuVY9fvqQ=
|
||||||
|
git.zhangdeman.cn/zhangdeman/wrapper v0.0.0-20240419103925-ee726ea6bcff/go.mod h1:Fo4XOiZPua4E4/Qzy3ZYS5zyd15bS/lsb3t6S6PQFGY=
|
||||||
|
git.zhangdeman.cn/zhangdeman/wrapper v0.0.0-20240422034417-8c922be06d95 h1:3lO4ap9p7kEA+4yL5ojG9mAWsz5sY28Nu2tSzAZEehw=
|
||||||
|
git.zhangdeman.cn/zhangdeman/wrapper v0.0.0-20240422034417-8c922be06d95/go.mod h1:Fo4XOiZPua4E4/Qzy3ZYS5zyd15bS/lsb3t6S6PQFGY=
|
||||||
|
github.com/BurntSushi/toml v1.3.2 h1:o7IhLm0Msx3BaB+n3Ag7L8EVlByGnpq14C4YWiu/gL8=
|
||||||
|
github.com/BurntSushi/toml v1.3.2/go.mod h1:CxXYINrC8qIiEnFrOxCa7Jy5BFHlXnUU2pbicEuybxQ=
|
||||||
|
github.com/axgle/mahonia v0.0.0-20180208002826-3358181d7394 h1:OYA+5W64v3OgClL+IrOD63t4i/RW7RqrAVl9LTZ9UqQ=
|
||||||
|
github.com/axgle/mahonia v0.0.0-20180208002826-3358181d7394/go.mod h1:Q8n74mJTIgjX4RBBcHnJ05h//6/k6foqmgE45jTQtxg=
|
||||||
|
github.com/go-ini/ini v1.67.0 h1:z6ZrTEZqSWOTyH2FlglNbNgARyHG8oLW9gMELqKr06A=
|
||||||
|
github.com/go-ini/ini v1.67.0/go.mod h1:ByCAeIL28uOIIG0E3PJtZPDL8WnHpFKFOtgjp+3Ies8=
|
||||||
|
github.com/mitchellh/go-homedir v1.1.0 h1:lukF9ziXFxDFPkA1vsr5zpc1XuPDn/wFntq5mG+4E0Y=
|
||||||
|
github.com/mitchellh/go-homedir v1.1.0/go.mod h1:SfyaCUpYCn1Vlf4IUYiD9fPX4A5wJrkLzIz1N1q0pr0=
|
||||||
|
github.com/mozillazg/go-pinyin v0.20.0 h1:BtR3DsxpApHfKReaPO1fCqF4pThRwH9uwvXzm+GnMFQ=
|
||||||
|
github.com/mozillazg/go-pinyin v0.20.0/go.mod h1:iR4EnMMRXkfpFVV5FMi4FNB6wGq9NV6uDWbUuPhP4Yc=
|
||||||
|
github.com/spaolacci/murmur3 v1.1.0 h1:7c1g84S4BPRrfL5Xrdp6fOJ206sU9y293DDHaoy0bLI=
|
||||||
|
github.com/spaolacci/murmur3 v1.1.0/go.mod h1:JwIasOWyU6f++ZhiEuf87xNszmSA2myDM2Kzu9HwQUA=
|
||||||
|
gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
|
||||||
|
gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
|
||||||
|
gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
|
||||||
@ -9,6 +9,11 @@ package swagger
|
|||||||
|
|
||||||
import (
|
import (
|
||||||
"git.zhangdeman.cn/gateway/api-doc/define"
|
"git.zhangdeman.cn/gateway/api-doc/define"
|
||||||
|
"git.zhangdeman.cn/gateway/api-doc/util"
|
||||||
|
"git.zhangdeman.cn/zhangdeman/consts"
|
||||||
|
"git.zhangdeman.cn/zhangdeman/wrapper"
|
||||||
|
"net/http"
|
||||||
|
"strings"
|
||||||
)
|
)
|
||||||
|
|
||||||
// Generate 生成文档
|
// Generate 生成文档
|
||||||
@ -16,6 +21,62 @@ import (
|
|||||||
// Author : zhangdeman001@ke.com<张德满>
|
// Author : zhangdeman001@ke.com<张德满>
|
||||||
//
|
//
|
||||||
// Date : 18:17 2024/4/19
|
// Date : 18:17 2024/4/19
|
||||||
func Generate(docInfo *define.Info) (*define.Swagger, error) {
|
func Generate(docConfig *define.SwaggerInput) (*define.Swagger, error) {
|
||||||
return nil, nil
|
formatDocConfig(docConfig)
|
||||||
|
swaggerInfo := &define.Swagger{
|
||||||
|
Schemes: docConfig.Schemes,
|
||||||
|
Swagger: define.SwaggerVersion2,
|
||||||
|
Host: docConfig.Host,
|
||||||
|
BasePath: docConfig.BasePath,
|
||||||
|
Info: docConfig.Info,
|
||||||
|
Paths: map[string]map[string]define.SwaggerPathConfig{},
|
||||||
|
Definitions: map[string]define.SwaggerDefinition{},
|
||||||
|
}
|
||||||
|
return swaggerInfo, nil
|
||||||
|
}
|
||||||
|
|
||||||
|
// formatDocConfig 格式化填充dock配置
|
||||||
|
//
|
||||||
|
// Author : go_developer@163.com<白茶清欢>
|
||||||
|
//
|
||||||
|
// Date : 10:54 2024/4/22
|
||||||
|
func formatDocConfig(docConfig *define.SwaggerInput) {
|
||||||
|
if docConfig.Schemes == nil {
|
||||||
|
docConfig.Schemes = make([]string, 0)
|
||||||
|
}
|
||||||
|
for _, itemPath := range docConfig.PathConfigList {
|
||||||
|
// 默认请求类型 application/json
|
||||||
|
itemPath.ContentType = strings.TrimSpace(itemPath.ContentType)
|
||||||
|
itemPath.ContentType = wrapper.TernaryOperator.String(len(itemPath.ContentType) == 0, consts.MimeTypeJson, wrapper.String(itemPath.ContentType)).Value()
|
||||||
|
// 默认post请求
|
||||||
|
itemPath.Method = strings.TrimSpace(itemPath.Method)
|
||||||
|
itemPath.Method = wrapper.TernaryOperator.String(len(itemPath.ContentType) == 0, http.MethodPost, wrapper.String(strings.ToUpper(itemPath.Method))).Value()
|
||||||
|
// 默认summary
|
||||||
|
itemPath.Summary = strings.TrimSpace(itemPath.Summary)
|
||||||
|
itemPath.Summary = wrapper.TernaryOperator.String(len(itemPath.Summary) == 0, wrapper.String("接口 : "+itemPath.Uri), wrapper.String(itemPath.Summary)).Value()
|
||||||
|
// 默认标签
|
||||||
|
itemPath.TagList = wrapper.TernaryOperator.Array(len(itemPath.TagList) == 0, wrapper.ArrayType([]string{"未分组"}), wrapper.ArrayType(itemPath.TagList)).ToStringSlice()
|
||||||
|
for _, itemParam := range itemPath.ParameterList {
|
||||||
|
// 填充默认参数位置
|
||||||
|
itemParam.In = strings.TrimSpace(itemParam.In)
|
||||||
|
itemPath.Summary = wrapper.TernaryOperator.String(len(itemParam.In) == 0, wrapper.String(util.GetParameterDefaultLocation(itemPath.Method)), wrapper.String(itemParam.In)).Value()
|
||||||
|
|
||||||
|
// 参数类型没填, 按照字符串处理
|
||||||
|
itemParam.Type = strings.TrimSpace(itemParam.Type)
|
||||||
|
itemParam.Type = wrapper.TernaryOperator.String(len(itemParam.Type) == 0, wrapper.String(itemParam.Type), wrapper.String(itemParam.Type)).Value()
|
||||||
|
|
||||||
|
// 参数描述
|
||||||
|
itemParam.Description = strings.TrimSpace(itemParam.Description)
|
||||||
|
itemParam.Description = wrapper.TernaryOperator.String(len(itemParam.Description) == 0, wrapper.String(itemParam.Type+" : "+itemParam.Name), wrapper.String(itemParam.Description)).Value()
|
||||||
|
}
|
||||||
|
|
||||||
|
for _, itemResponse := range itemPath.ResponseList {
|
||||||
|
// 默认返回数据类型
|
||||||
|
itemResponse.Type = strings.TrimSpace(itemResponse.Type)
|
||||||
|
itemResponse.Type = wrapper.TernaryOperator.String(len(itemResponse.Type) == 0, consts.DataTypeString, wrapper.String(itemResponse.Type)).Value()
|
||||||
|
// 填充默认描述
|
||||||
|
itemResponse.Description = strings.TrimSpace(itemResponse.Description)
|
||||||
|
itemResponse.Description = wrapper.TernaryOperator.String(len(itemResponse.Description) == 0, wrapper.String(itemResponse.Type+" : "+itemResponse.Field), wrapper.String(itemResponse.Description)).Value()
|
||||||
|
}
|
||||||
|
}
|
||||||
}
|
}
|
||||||
|
|||||||
45
util/tool.go
Normal file
45
util/tool.go
Normal file
@ -0,0 +1,45 @@
|
|||||||
|
// Package util ...
|
||||||
|
//
|
||||||
|
// Description : util ...
|
||||||
|
//
|
||||||
|
// Author : go_developer@163.com<白茶清欢>
|
||||||
|
//
|
||||||
|
// Date : 2024-04-22 11:15
|
||||||
|
package util
|
||||||
|
|
||||||
|
import (
|
||||||
|
"git.zhangdeman.cn/zhangdeman/consts"
|
||||||
|
"net/http"
|
||||||
|
"strings"
|
||||||
|
)
|
||||||
|
|
||||||
|
// GetParameterDefaultLocation 获取参数的默认位置
|
||||||
|
//
|
||||||
|
// Author : go_developer@163.com<白茶清欢>
|
||||||
|
//
|
||||||
|
// Date : 11:16 2024/4/22
|
||||||
|
func GetParameterDefaultLocation(requestMethod string) string {
|
||||||
|
requestMethod = strings.ToUpper(requestMethod)
|
||||||
|
// 没指定参数位置
|
||||||
|
switch requestMethod {
|
||||||
|
case http.MethodGet:
|
||||||
|
fallthrough
|
||||||
|
case http.MethodHead:
|
||||||
|
fallthrough
|
||||||
|
case http.MethodConnect:
|
||||||
|
fallthrough
|
||||||
|
case http.MethodOptions:
|
||||||
|
fallthrough
|
||||||
|
case http.MethodTrace:
|
||||||
|
return consts.RequestLocationQuery
|
||||||
|
case http.MethodPost:
|
||||||
|
fallthrough
|
||||||
|
case http.MethodPut:
|
||||||
|
fallthrough
|
||||||
|
case http.MethodPatch: // RFC 5789
|
||||||
|
fallthrough
|
||||||
|
case http.MethodDelete:
|
||||||
|
return consts.RequestLocationBody
|
||||||
|
}
|
||||||
|
return consts.RequestLocationQuery
|
||||||
|
}
|
||||||
Loading…
x
Reference in New Issue
Block a user