增加openapi文档基础的信息定义 + parameter基础定义
This commit is contained in:
parent
723d0e477c
commit
458d33cba5
@ -1,4 +1,4 @@
|
||||
// Package define ...
|
||||
// Package define openapi 文档数据结构定一
|
||||
//
|
||||
// Description : define ...
|
||||
//
|
||||
@ -6,3 +6,131 @@
|
||||
//
|
||||
// Date : 2024-04-23 22:16
|
||||
package define
|
||||
|
||||
// OpenapiDoc openapi文档结构, 文档规范参见 : https://openapi.apifox.cn/
|
||||
//
|
||||
// Author : go_developer@163.com<白茶清欢>
|
||||
//
|
||||
// Date : 12:16 2024/7/19
|
||||
type OpenapiDoc struct {
|
||||
Openapi string `json:"openapi" required:"true"` // 必选. 这个字符串必须是开放 API 规范版本号提到的符合语义化版本号规范的版本号。openapi字段应该被工具或者客户端用来解释 OpenAPI 文档.
|
||||
Info *Info `json:"info" required:"true"` // 必选。此字段提供 API 相关的元数据。相关工具可能需要这个字段。
|
||||
Servers []any `json:"servers"` // 服务环境
|
||||
Tags []TagItem `json:"tags"` // 全部标签列表
|
||||
Paths map[string]map[string]*PathConfig `json:"paths"` // 接口路径 -> 接口请求方法 -> 具体配置
|
||||
}
|
||||
|
||||
// PathConfig 接口的具体配置
|
||||
//
|
||||
// Author : go_developer@163.com<白茶清欢>
|
||||
//
|
||||
// Date : 12:22 2024/7/19
|
||||
type PathConfig struct {
|
||||
Title string `json:"title" required:"true"` // 必选. 应用的名称。
|
||||
Summary string `json:"summary"` // 一个可选的简要总结字符串，用来描述此路径内包含的所有操作。
|
||||
Deprecated bool `json:"deprecated"` // 是否已弃用
|
||||
Description string `json:"description"` // 一个可选的详细说明字符串，用于描述此路径包含的所有操作。 CommonMark syntax 可以被用来呈现富文本格式.
|
||||
Tags []string `json:"tags"` // 接口标签列表
|
||||
Parameters []*PathConfigParameter `json:"parameters"` // 参数列表
|
||||
RequestBody any `json:"request_body"` // 请求体配置
|
||||
}
|
||||
|
||||
// PathConfigParameter 参数配置
|
||||
//
|
||||
// Author : go_developer@163.com<白茶清欢>
|
||||
//
|
||||
// Date : 12:29 2024/7/19
|
||||
type PathConfigParameter struct {
|
||||
Name string `json:"name"` // 参数名称
|
||||
In string `json:"in"` // 必选. 参数的位置，可能的值有 "query", "header", "path" 或 "cookie"。
|
||||
Description string `json:"description"` // 对此参数的简要描述，这里可以包含使用示例。CommonMark syntax可以被用来呈现富文本格式.
|
||||
Required bool `json:"required"` // 标明此参数是否是必选参数。如果 参数位置 的值是 path，那么这个参数一定是 必选 的因此这里的值必须是true。其他的则视情况而定。此字段的默认值是false。
|
||||
Deprecated bool `json:"deprecated"` // 标明一个参数是被弃用的而且应该尽快移除对它的使用。
|
||||
Schema *PathConfigParameterSchema `json:"schema"` // 定义适用于此参数的类型结构。 Schema 对象 | Reference 对象
|
||||
AllowEmptyValue bool `json:"allowEmptyValue"` // 设置是否允许传递空参数，这只在参数值为query时有效，默认值是false。如果同时指定了style属性且值为n/a（无法被序列化）,那么此字段 allowEmptyValue应该被忽略。
|
||||
Style string `json:"style"` // 描述根据参数值类型的不同如何序列化参数。默认值为（基于in字段的值）：query 对应 form；path 对应 simple; header 对应 simple; cookie 对应 form。
|
||||
Explode bool `json:"explode"` // 当这个值为true时，参数值类型为array或object的参数使用数组内的值或对象的键值对生成带分隔符的参数值。对于其他类型的参数，这个字段没有任何影响。当 style 是 form时，这里的默认值是 true，对于其他 style 值类型，默认值是false。
|
||||
AllowReserved bool `json:"allowReserved"` // 决定此参数的值是否允许不使用%号编码使用定义于 RFC3986内的保留字符 :/?#[]@!$&'()*+,;=。 这个属性仅用于in的值是query时，此字段的默认值是false。
|
||||
}
|
||||
|
||||
// PathConfigParameterSchema ...
|
||||
//
|
||||
// Author : go_developer@163.com<白茶清欢>
|
||||
//
|
||||
// Date : 12:32 2024/7/19
|
||||
type PathConfigParameterSchema struct {
|
||||
Description string `json:"description"` // 参数描述
|
||||
Format string `json:"format"` // 映射到go数据类型时哪一个类型
|
||||
Type string `json:"type"` // swagger定义的数据类型
|
||||
Properties map[string]any `json:"properties"` // 属性, TODO : 待完善
|
||||
}
|
||||
|
||||
type RequestBody struct {
|
||||
}
|
||||
|
||||
// Info 信息
|
||||
//
|
||||
// Author : go_developer@163.com<白茶清欢>
|
||||
//
|
||||
// Date : 16:10 2024/4/19
|
||||
type Info struct {
|
||||
Description string `json:"description"` // 对应用的简短描述。 CommonMark syntax 可以被用来表示富文本呈现。
|
||||
Title string `json:"title" required:"true"` // 必选. 应用的名称。
|
||||
TermsOfService string `json:"termsOfService"` // 指向服务条款的 URL 地址，必须是 URL 地址格式。
|
||||
Contact Contact `json:"contact"` // 联系方式
|
||||
License License `json:"license"` // 开源协议
|
||||
Version string `json:"version" required:"true"` // 必选. API 文档的版本信息（注意：这个版本和开放 API 规范版本没有任何关系）。
|
||||
}
|
||||
|
||||
// Contact 联系人信息
|
||||
//
|
||||
// Author : go_developer@163.com<白茶清欢>
|
||||
//
|
||||
// Date : 16:08 2024/4/19
|
||||
type Contact struct {
|
||||
Name string `json:"name"` // 人或组织的名称。
|
||||
Url string `json:"url"` // 指向联系人信息的 URL 地址，必须是 URL 地址格式。
|
||||
Email string `json:"email"` // 人或组织的 email 地址，必须是 email 地址格式
|
||||
}
|
||||
|
||||
// License 开源协议
|
||||
//
|
||||
// Author : go_developer@163.com<白茶清欢>
|
||||
//
|
||||
// Date : 16:09 2024/4/19
|
||||
type License struct {
|
||||
Name string `json:"name"` // 开源协议名
|
||||
Url string `json:"url"` // 开源协议地址
|
||||
}
|
||||
|
||||
// ServerItem server 对象结构
|
||||
//
|
||||
// Author : go_developer@163.com<白茶清欢>
|
||||
//
|
||||
// Date : 14:18 2024/7/19
|
||||
type ServerItem struct {
|
||||
Url string `json:"url" required:"true"` // 必选. 指向目标主机的 URL 地址。这个 URL 地址支持服务器变量而且可能是相对路径，表示主机路径是相对于本文档所在的路径。当一个变量被命名为类似{brackets}时需要替换此变量。
|
||||
Description string `json:"description"` // 一个可选的字符串，用来描述此 URL 地址。CommonMark syntax可以被用来呈现富文本格式.
|
||||
Variables map[string]*ServerItemVariable `json:"variables"` // 当 url 中出现变量名的时候, 会从次变量中读取数据替换到url中. 变量名 -> 变量配置
|
||||
}
|
||||
|
||||
// ServerItemVariable ...
|
||||
//
|
||||
// Author : go_developer@163.com<白茶清欢>
|
||||
//
|
||||
// Date : 14:22 2024/7/19
|
||||
type ServerItemVariable struct {
|
||||
Default string `json:"default"` // 变量默认值
|
||||
Description string `json:"description"` // 变量描述
|
||||
Enum []string `json:"enum"` // 变量枚举值
|
||||
}
|
||||
|
||||
// TagItem 每一个标签数据结构
|
||||
//
|
||||
// Author : go_developer@163.com<白茶清欢>
|
||||
//
|
||||
// Date : 12:18 2024/7/19
|
||||
type TagItem struct {
|
||||
Name string `json:"name"` // 标签名称
|
||||
Description string `json:"description"` // 标签描述
|
||||
}
|
||||
|
||||
@ -7,40 +7,6 @@
|
||||
// Date : 2024-04-19 12:07
|
||||
package define
|
||||
|
||||
// Contact 联系人信息
|
||||
//
|
||||
// Author : go_developer@163.com<白茶清欢>
|
||||
//
|
||||
// Date : 16:08 2024/4/19
|
||||
type Contact struct {
|
||||
Name string `json:"name"` // 姓名
|
||||
Url string `json:"url"` // 主页地址
|
||||
Email string `json:"email"` // 邮箱
|
||||
}
|
||||
|
||||
// License 开源协议
|
||||
//
|
||||
// Author : go_developer@163.com<白茶清欢>
|
||||
//
|
||||
// Date : 16:09 2024/4/19
|
||||
type License struct {
|
||||
Name string `json:"name"` // 开源协议名
|
||||
Url string `json:"url"` // 开源协议地址
|
||||
}
|
||||
|
||||
// Info 信息
|
||||
//
|
||||
// Author : go_developer@163.com<白茶清欢>
|
||||
//
|
||||
// Date : 16:10 2024/4/19
|
||||
type Info struct {
|
||||
Description string `json:"description"` // 文档描述
|
||||
Title string `json:"title"` // 文档标题
|
||||
Contact Contact `json:"contact"` // 联系方式
|
||||
License License `json:"license"` // 开源协议
|
||||
Version string `json:"version"` // 文档版本
|
||||
}
|
||||
|
||||
// SwaggerPathConfig ...
|
||||
//
|
||||
// Author : zhangdeman001@ke.com<张德满>
|
||||
|
||||
23
parser.go
Normal file
23
parser.go
Normal file
@ -0,0 +1,23 @@
|
||||
// Package api_doc ...
|
||||
//
|
||||
// Description : api_doc ...
|
||||
//
|
||||
// Author : go_developer@163.com<白茶清欢>
|
||||
//
|
||||
// Date : 2024-07-19 11:45
|
||||
package api_doc
|
||||
|
||||
var (
|
||||
Parser = &parser{}
|
||||
)
|
||||
|
||||
type parser struct {
|
||||
}
|
||||
|
||||
func (p *parser) Openapi3() {
|
||||
|
||||
}
|
||||
|
||||
func (p *parser) swagger2() {
|
||||
|
||||
}
|
||||
Loading…
x
Reference in New Issue
Block a user