239 lines
16 KiB
Go
239 lines
16 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]*PathItemConfig `json:"paths"` // 接口路径 -> 接口请求方法 -> 具体配置
|
||
}
|
||
|
||
// PathItemConfig 接口的具体配置
|
||
// 描述对一个路径可执行的有效操作。
|
||
// 依赖与 ACL constraints 的设置，一个Path Item可以是一个空对象，
|
||
// 文档的读者仍然可以看到这个路径，但是他们将无法了解到对这个路径可用的任何操作和参数。
|
||
//
|
||
// Author : go_developer@163.com<白茶清欢>
|
||
//
|
||
// Date : 12:22 2024/7/19
|
||
type PathItemConfig struct {
|
||
Ref string `json:"$ref"` // 指定对此路径的外部定义的引用，引用的格式必须符合 Path Item 对象 的格式，如果引用的外部定义和此对象内的其他定义有冲突，该如何处理冲突尚未被定义。
|
||
Summary string `json:"summary"` // 一个可选的简要总结字符串，用来描述此路径内包含的所有操作。
|
||
Deprecated bool `json:"deprecated"` // 是否已弃用
|
||
Description string `json:"description"` // 一个可选的详细说明字符串，用于描述此路径包含的所有操作。 CommonMark syntax 可以被用来呈现富文本格式.
|
||
Tags []string `json:"tags"` // 接口标签列表
|
||
Get *PathItemOperationConfig `json:"get"` // 定义适用于此路径的 GET 操作。
|
||
Put *PathItemOperationConfig `json:"put"` // 定义适用于此路径的 PUT 操作。
|
||
Post *PathItemOperationConfig `json:"post"` // 定义适用于此路径的 POST 操作。
|
||
Delete *PathItemOperationConfig `json:"delete"` // DELETE
|
||
Options *PathItemOperationConfig `json:"options"` // 定义适用于此路径的 OPTIONS 操作。
|
||
Head string `json:"head"` // 定义适用于此路径的 HEAD 操作。
|
||
Patch string `json:"patch"` // 定义适用于此路径的 PATCH 操作。
|
||
Trace string `json:"trace"` // 定义适用于此路径的 TRACE 操作。
|
||
Parameters []*PathConfigParameter `json:"parameters"` // 参数列表, 对于所有请求生效
|
||
}
|
||
|
||
// PathItemOperationConfig 描述对路径的某个操作。
|
||
//
|
||
// Author : go_developer@163.com<白茶清欢>
|
||
//
|
||
// Date : 16:20 2024/7/19
|
||
type PathItemOperationConfig struct {
|
||
Tags []string `json:"tags"` // 用于控制API文档的标签列表，标签可以用于在逻辑上分组对资源的操作或作为其它用途的先决条件。
|
||
Summary string `json:"summary"` // 对此操作行为的简短描述。
|
||
Description string `json:"description"` // 对此操作行为的详细解释。CommonMark syntax可以被用来呈现富文本格式.
|
||
ExternalDocs *ExternalDocs `json:"externalDocs"` // 附加的外部文档。
|
||
OperationID string `json:"operationId"` // 用于标识此操作的唯一字符串，这个id在此API内包含的所有操作中必须是唯一的。相关的工具和库可能会使用此operationId来唯一的标识一个操作，因此推荐在命名时符合一般的编程命名习惯
|
||
Parameters []*PathConfigParameter `json:"parameters"` // 定义可用于此操作的参数列表，如果一个同名的参数已经存在于 Path Item，那么这里的定义会覆盖它但是不能移除上面的定义。这个列表不允许包含重复的参数，参数的唯一性由 name 和 location 的组合来确定。这个列表可以使用 Reference 对象 来连接定义于 OpenAPI 对象 components/parameters 的参数。
|
||
RequestBody any `json:"requestBody"` // 可用于此操作的请求体。requestBody 只能被用于HTTP 1.1 规范 RFC7231 中明确定义了包含请求体的请求方法，在其他没有明确定义的请求方法中，requestBody的消费者应该应该忽略requestBody。
|
||
}
|
||
|
||
// PathItemOperationRequestBody ...
|
||
//
|
||
// Author : go_developer@163.com<白茶清欢>
|
||
//
|
||
// Date : 16:44 2024/7/19
|
||
type PathItemOperationRequestBody struct {
|
||
Required bool `json:"required"` // 指定请求体是不是应该被包含在请求中，默认值是false。
|
||
Description string `json:"description"` // 对请求体的简要描述，可以包含使用示例，CommonMark syntax可以被用来呈现富文本格式.
|
||
Content map[string]any `json:"content"` // 必选. 请求体的内容。请求体的属性key是一个媒体类型或者媒体类型范围，值是对应媒体类型的示例数据。对于能匹配多个key的请求，定义更明确的请求会更优先被匹配。比如text/plain会覆盖text/*的定义。
|
||
Ref string `json:"$ref"` // 一个允许引用规范内部的其他部分或外部规范的对象。 Reference 对象 定义于 JSON Reference 且遵循相同的结构、行为和规则。
|
||
}
|
||
|
||
// ExternalDocs 外部文档配置
|
||
//
|
||
// Author : go_developer@163.com<白茶清欢>
|
||
//
|
||
// Date : 16:30 2024/7/19
|
||
type ExternalDocs struct {
|
||
Url string `json:"url"` // 必选. 外部文档的URL地址，这个值必须是URL地址格式。
|
||
Description string `json:"description"` // 对引用的外部文档的简短描述。CommonMark syntax可以被用来呈现富文本格式.
|
||
}
|
||
|
||
// 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 *Schema `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。
|
||
Ref string `json:"$ref"` // 一个允许引用规范内部的其他部分或外部规范的对象。 Reference 对象 定义于 JSON Reference 且遵循相同的结构、行为和规则。
|
||
}
|
||
|
||
// Schema ...
|
||
//
|
||
// Author : go_developer@163.com<白茶清欢>
|
||
//
|
||
// Date : 12:32 2024/7/19
|
||
type Schema struct {
|
||
Nullable bool `json:"nullable"` // 对于定义的schema，允许发送 null 值。默认值是 false.
|
||
Discriminator *SchemaDiscriminator `json:"discriminator"` // 说白了, 就是一个字段可能是不同的数据结构。。。
|
||
ReadOnly bool `json:"readOnly"` // 仅与 Schema "properties" 定义有关。 声明此属性是 "readonly" 的。这意味着它可以作为 response 的一部分但不应该作为 request 的一部分被发送。如果一个 property 的 readOnly 被标记为 true 且在 required 列表中，required 将只作用于 response。一个 property 的 readOnly 和 writeOnly 不允许同时被标记为 true。默认值是 false。
|
||
WriteOnly bool `json:"writeOnly"` // 仅与 Schema "properties" 定义有关。声明此 property 为 "write only"。所以它可以作为 request 的一部分而不应该作为 response 的一部分被发送。如果一个 property 的 writeOnly 被标记为 true 且在 required 列表中，required 将只作用于 request。一个 property 的 readOnly 和 writeOnly 不能同时被标记为 true。默认值是 false。
|
||
Xml XML `json:"xml"` // 这只能用于 properties schemas，在 root schemas 中没有效果。
|
||
ExternalDocs *ExternalDocs `json:"externalDocs"` // 此 schema 附加的外部文档。
|
||
Example string `json:"example"` // 一个用于示范此 schema实例的示例，可以是任意格式。为了表达无法用 JSON 或 YAML 格式呈现的示例，可以使用 string 类型的值，且在必要的地方需要使用字符转义。
|
||
Deprecated bool `json:"deprecated"` // 表示一个 schema 是废弃的，应该逐渐被放弃使用。默认值是 false.
|
||
Properties map[string]*Property `json:"properties"` // 数据字段 => 数据规则
|
||
}
|
||
|
||
// Property 是从 JSON Schema 提取出来的，但是做了一些调整以适应 OpenAPI Specification。
|
||
//
|
||
// Author : go_developer@163.com<白茶清欢>
|
||
//
|
||
// Date : 17:05 2024/7/19
|
||
type Property struct {
|
||
Type string `json:"type"` // 数据类型, swagger本身的定义
|
||
Format string `json:"format"` // 对应编程语言中的数据类型描述
|
||
Default any `json:"default"` // 默认值 : 不同于 JSON Schema，这个值必须符合定义与相同级别的 Schema 对象 中定义的类型，比如 type 是 string，那么 default 可以是 "foo" 但不能是 1。
|
||
Description string `json:"description"` // 数据描述, CommonMark syntax可以被用来呈现富文本格式.
|
||
AllOf []*PropertyXOf `json:"allOf"` // type 是一个对象, allOf 指向对象描述
|
||
OneOf []*PropertyXOf `json:"oneOf"` // type 是一个对象, allOf 指向对象描述
|
||
AnyOf []*PropertyXOf `json:"anyOf"` // type 是一个对象, allOf 指向对象描述
|
||
Items *PropertyXOf `json:"items"` // items 必须存在如果 type 的值是 array。
|
||
}
|
||
|
||
// PropertyXOf ...
|
||
//
|
||
// Author : go_developer@163.com<白茶清欢>
|
||
//
|
||
// Date : 17:13 2024/7/19
|
||
type PropertyXOf struct {
|
||
Ref string `json:"$ref"` // 引用的结构描述
|
||
}
|
||
|
||
// SchemaDiscriminator 当一个 request bodies 或 response payloads 可以是多种 schemas 时，可以使用一个 discriminator 对象来帮助序列化、反序列化和校验
|
||
// discriminator 属性仅在与 oneOf, anyOf, allOf 这几个复合关键字之一一起使用时才合法.
|
||
//
|
||
// Author : go_developer@163.com<白茶清欢>
|
||
//
|
||
// Date : 16:48 2024/7/19
|
||
type SchemaDiscriminator struct {
|
||
PropertyName string `json:"propertyName"` // 必选. 在 payload 中表示 discriminator 值的属性的名称。
|
||
Mapping map[string]string `json:"mapping"` // 一个映射 payload 中的值和 schema 名称或引用的对象。
|
||
}
|
||
|
||
// XML 一个为 XML 模型定义微调过的元数据对象。
|
||
//
|
||
// Author : go_developer@163.com<白茶清欢>
|
||
//
|
||
// Date : 16:56 2024/7/19
|
||
type XML struct {
|
||
Name string `json:"name"` // 替换用于描述元素/属性的结构特性的名称。当在 items 内定义时将会影响处于此列表中的每个元素的名称。当定义于 items 之上时将会影响它说包裹的元素且仅当 wrapped 是 true 时，如果 wrapped 是 false 时它将会被忽略
|
||
Namespace string `json:"namespace"` // 命名空间定义的 URI。其值必须是绝对 URI。
|
||
Prefix string `json:"prefix"` // 用于 name 的前缀。
|
||
Attribute bool `json:"attribute"` // 声明此特性定义会被转换为一个属性而不是一个元素。默认值是 false。
|
||
Wrapped bool `json:"wrapped"` // 只可被用于数组定义。表示数组是否被包裹（比如, <books><book/><book/></books>）或未被包裹（<book/><book/>）。默认值是 false。此定义只在 type 为 array（位于 items 之上） 时生效。
|
||
}
|
||
|
||
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"` // 标签描述
|
||
}
|