137 lines
7.5 KiB
Go
137 lines
7.5 KiB
Go
// Package define openapi 文档数据结构定一
|
||
//
|
||
// Description : define ...
|
||
//
|
||
// Author : go_developer@163.com<白茶清欢>
|
||
//
|
||
// 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"` // 标签描述
|
||
}
|