api-doc/define/openapi.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,omitempty" required:"true"` // 必选。此字段提供 API 相关的元数据。相关工具可能需要这个字段。
	Servers    []*ServerItem          `json:"servers"`                        // 服务环境
	Components *Components            `json:"components,omitempty"`           // 数据结构
	Tags       []*TagItem             `json:"tags"`                           // 全部标签列表
	Paths      map[string]*PathConfig `json:"paths"`                          // 接口路径 -> 接口请求方法 -> 具体配置
}

// Components 数据结构定义
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 21:22 2024/7/19
type Components struct {
	Schemas map[string]*Schema `json:"schemas"` // 数据结构定义
}

// PathConfig ...
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 18:06 2024/7/19
type PathConfig struct {
	Get     *PathItemOperationConfig `json:"get,omitempty"`     // 定义适用于此路径的 GET 操作。
	Put     *PathItemOperationConfig `json:"put,omitempty"`     // 定义适用于此路径的 PUT 操作。
	Post    *PathItemOperationConfig `json:"post,omitempty"`    // 定义适用于此路径的 POST 操作。
	Delete  *PathItemOperationConfig `json:"delete,omitempty"`  // DELETE
	Options *PathItemOperationConfig `json:"options,omitempty"` // 定义适用于此路径的 OPTIONS 操作。
	Head    *PathItemOperationConfig `json:"head,omitempty"`    // 定义适用于此路径的 HEAD 操作。
	Patch   *PathItemOperationConfig `json:"patch,omitempty"`   // 定义适用于此路径的 PATCH 操作。
	Trace   *PathItemOperationConfig `json:"trace,omitempty"`   // 定义适用于此路径的 TRACE 操作。
	Connect *PathItemOperationConfig `json:"connect,omitempty"` // 定义适用于此路径的 CONNECT 操作。
}

// 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"`                 // 接口标签列表
	Parameters  []*PathConfigParameter `json:"parameters,omitempty"` // 参数列表, 对于所有请求生效
}

// 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,omitempty"` // 附加的外部文档。
	OperationID  string                 `json:"operationId"`            // 用于标识此操作的唯一字符串，这个id在此API内包含的所有操作中必须是唯一的。相关的工具和库可能会使用此operationId来唯一的标识一个操作，因此推荐在命名时符合一般的编程命名习惯
	Parameters   []*PathConfigParameter `json:"parameters,omitempty"`   // 定义可用于此操作的参数列表，如果一个同名的参数已经存在于 Path Item，那么这里的定义会覆盖它但是不能移除上面的定义。这个列表不允许包含重复的参数，参数的唯一性由 name 和 location 的组合来确定。这个列表可以使用 Reference 对象 来连接定义于 OpenAPI 对象 components/parameters 的参数。
	RequestBody  *RequestBody           `json:"requestBody,omitempty"`  // 可用于此操作的请求体。requestBody 只能被用于HTTP 1.1 规范 RFC7231 中明确定义了包含请求体的请求方法，在其他没有明确定义的请求方法中，requestBody的消费者应该应该忽略requestBody。
	Responses    map[string]*Response   `json:"responses"`              // 描述一个操作可能发生的响应的响应码与响应包含的响应体的对象。default字段可以用来标记一个响应适用于其他未被规范明确定义的HTTP响应码的默认响应。一个Responses 对象必须至少包含一个响应码，而且是成功的响应。
	Callbacks    map[string]any         `json:"callbacks,omitempty"`    // 一组相对于父操作的可能出现的回调映射，映射中的每一个键都唯一的映射一个 Callback 对象
	Deprecated   bool                   `json:"deprecated"`             // 声明此操作已经被废弃，使用者应该尽量避免使用此操作，默认的值是 false。
	Security     any                    `json:"security,omitempty"`     // 声明那种安全机制可用于此操作。这个列表可以包含多种可用于此操作的安全需求对象，但是在认证一个请求时应该仅使用其中一种。这里的定义会覆盖任何在顶层 security 中的安全声明，因此可以声明一个空数组来变相的移除顶层的安全声明。
	Servers      []*ServerItem          `json:"servers,omitempty"`      // 一个可用于此操作的额外的 server 数组，这里的定义会覆盖 Path Item 对象 或 顶层的定义。
}

// 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,omitempty"`        // 定义适用于此参数的类型结构。 Schema 对象 | Reference 对象
	AllowEmptyValue bool    `json:"allowEmptyValue"`         // 设置是否允许传递空参数，这只在参数值为query时有效，默认值是false。如果同时指定了style属性且值为n/a（无法被序列化）,那么此字段 allowEmptyValue应该被忽略。
	Style           string  `json:"style,omitempty"`         // 描述根据参数值类型的不同如何序列化参数。默认值为（基于in字段的值）：query 对应 form；path 对应 simple; header 对应 simple; cookie 对应 form。
	Explode         bool    `json:"explode,omitempty"`       // 当这个值为true时，参数值类型为array或object的参数使用数组内的值或对象的键值对生成带分隔符的参数值。对于其他类型的参数，这个字段没有任何影响。当 style 是 form时，这里的默认值是 true，对于其他 style 值类型，默认值是false。
	AllowReserved   bool    `json:"allowReserved,omitempty"` // 决定此参数的值是否允许不使用%号编码使用定义于 RFC3986内的保留字符 :/?#[]@!$&'()*+,;=。 这个属性仅用于in的值是query时，此字段的默认值是false。
	Ref             string  `json:"$ref,omitempty"`          // 一个允许引用规范内部的其他部分或外部规范的对象。 Reference 对象 定义于 JSON Reference 且遵循相同的结构、行为和规则。
}

// Schema ...
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 12:32 2024/7/19
type Schema struct {
	Nullable         bool                 `json:"nullable,omitempty"`           // 对于定义的schema，允许发送 null 值。默认值是 false.
	Discriminator    *SchemaDiscriminator `json:"discriminator,omitempty"`      // 说白了, 就是一个字段可能是不同的数据结构。。。
	ReadOnly         bool                 `json:"readOnly,omitempty"`           // 仅与 Schema "properties" 定义有关。 声明此属性是 "readonly" 的。这意味着它可以作为 response 的一部分但不应该作为 request 的一部分被发送。如果一个 property 的 readOnly 被标记为 true 且在 required 列表中，required 将只作用于 response。一个 property 的 readOnly 和 writeOnly 不允许同时被标记为 true。默认值是 false。
	WriteOnly        bool                 `json:"writeOnly,omitempty"`          // 仅与 Schema "properties" 定义有关。声明此 property 为 "write only"。所以它可以作为 request 的一部分而不应该作为 response 的一部分被发送。如果一个 property 的 writeOnly 被标记为 true 且在 required 列表中，required 将只作用于 request。一个 property 的 readOnly 和 writeOnly 不能同时被标记为 true。默认值是 false。
	Xml              *XML                 `json:"xml,omitempty"`                // 这只能用于 properties schemas，在root schemas 中没有效果。
	ExternalDocs     *ExternalDocs        `json:"externalDocs,omitempty"`       // 此 schema 附加的外部文档。
	Example          any                  `json:"example,omitempty"`            // 一个用于示范此 schema实例的示例，可以是任意格式。为了表达无法用 JSON 或 YAML 格式呈现的示例，可以使用 string 类型的值，且在必要的地方需要使用字符转义。
	Description      string               `json:"description,omitempty"`        // 一个用于示范此 schema实例的示例，可以是任意格式。为了表达无法用 JSON 或 YAML 格式呈现的示例，可以使用 string 类型的值，且在必要的地方需要使用字符转义。
	Deprecated       bool                 `json:"deprecated,omitempty"`         // 表示一个 schema 是废弃的，应该逐渐被放弃使用。默认值是 false.
	Properties       map[string]*Property `json:"properties,omitempty"`         // 数据字段 => 数据规则
	Required         []string             `json:"required,omitempty"`           // 必传属性列表
	Enum             []any                `json:"enum,omitempty"`               // 枚举值列表
	XEnumDescription map[string]string    `json:"x-enumDescriptions,omitempty"` // 枚举值描述的扩展, redoc-free支持
	Type             string               `json:"type,omitempty"`               // 类型
	Items            *PropertyXOf         `json:"items,omitempty"`              // items 必须存在如果 type 的值是 array。
	OneOf            []*PropertyXOf       `json:"oneOf,omitempty"`              // type 是一个对象, allOf 指向对象描述
	Ref              string               `json:"$ref,omitempty"`               // 类型引用
	Format           string               `json:"format,omitempty"`             // 格式化类型
	Maximum          *int64               `json:"maximum,omitempty"`            // 最大值
	Minimum          *int64               `json:"minimum,omitempty"`            // 最小值
	MinLength        *int64               `json:"minLength,omitempty"`          // 字符串最小长度
	MaxLength        *int64               `json:"maxLength,omitempty"`          // 字符串最大长度
	Default          any                  `json:"default,omitempty"`            // 默认值
}

// Property 是从 JSON Schema 提取出来的，但是做了一些调整以适应 OpenAPI Specification。
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 17:05 2024/7/19
type Property struct {
	Type                 string               `json:"type,omitempty"`                 // 数据类型, swagger本身的定义
	Format               string               `json:"format,omitempty"`               // 对应编程语言中的数据类型描述
	Enum                 []any                `json:"enum,omitempty"`                 // 枚举值列表
	XEnumDescription     map[string]string    `json:"x-enumDescriptions,omitempty"`   // 枚举值描述的扩展, redoc-free支持
	Default              any                  `json:"default,omitempty"`              // 默认值 : 不同于 JSON Schema，这个值必须符合定义与相同级别的 Schema 对象 中定义的类型，比如 type 是 string，那么 default 可以是 "foo" 但不能是 1。
	Description          string               `json:"description,omitempty"`          // 数据描述, CommonMark syntax可以被用来呈现富文本格式.
	Example              any                  `json:"example,omitempty"`              // 媒体类型的示例。示例对象应该符合此媒体类型的格式， 这里指定的example对象 object is mutually exclusive of the examples object. 而且如果引用的schema也包含示例，在这里指定的example值将会覆盖schema提供的示例。
	Maximum              *int64               `json:"maximum,omitempty"`              // 最大值
	Minimum              *int64               `json:"minimum,omitempty"`              // 最小值
	MinLength            *int64               `json:"minLength,omitempty"`            // 字符串最小长度
	MaxLength            *int64               `json:"maxLength,omitempty"`            // 字符串最大长度
	AllOf                []*PropertyXOf       `json:"allOf,omitempty"`                // type 是一个对象, allOf 指向对象描述
	OneOf                []*PropertyXOf       `json:"oneOf,omitempty"`                // type 是一个对象, allOf 指向对象描述
	AnyOf                []*PropertyXOf       `json:"anyOf,omitempty"`                // type 是一个对象, allOf 指向对象描述
	Items                *PropertyXOf         `json:"items,omitempty"`                // items 必须存在如果 type 的值是 array。
	AdditionalProperties *PropertyXOf         `json:"additionalProperties,omitempty"` // additionalProperties 是一个用于描述模型中包含未在属性列表中定义的额外属性的选项。它允许接受任意的一个或多个键值对。它的作用是为了在模型定义中包含未知或动态属性。通常，在设计 API 时，我们无法预先知道 API 用户会传递什么样的额外属性，这时就可以使用 additionalProperties 功能来灵活地处理这些未知属性。
	Properties           map[string]*Property `json:"properties,omitempty"`           // type = object 时, 定义对象属性
	Ref                  string               `json:"$ref,omitempty"`                 // 对描述的引用
}

// PropertyXOf ...
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 17:13 2024/7/19
type PropertyXOf struct {
	Type    string `json:"type,omitempty"`    // 基础类型
	Format  string `json:"format,omitempty"`  // 真实类型
	Maximum *int64 `json:"maximum,omitempty"` // 最大值
	Minimum *int64 `json:"minimum,omitempty"` // 最小值
	Ref     string `json:"$ref,omitempty"`    // 引用的结构描述
	// Items   *PropertyXOf `json:"items,omitempty"`   // 数据每一项已用类型
}

// 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 之上） 时生效。
}

// RequestBody 定义请求体
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 17:17 2024/7/19
type RequestBody struct {
	Required    bool              `json:"required"`              // 指定请求体是不是应该被包含在请求中，默认值是false。
	Description string            `json:"description,omitempty"` // 对请求体的简要描述，可以包含使用示例，CommonMark syntax可以被用来呈现富文本格式
	Content     map[string]*Media `json:"content,omitempty"`     // content_type => 相应数据描述的映射 必选. 请求体的内容。请求体的属性key是一个媒体类型或者媒体类型范围，值是对应媒体类型的示例数据。对于能匹配多个key的请求，定义更明确的请求会更优先被匹配。比如text/plain会覆盖text/*的定义。
	Ref         string            `json:"$ref,omitempty"`        // 一个允许引用规范内部的其他部分或外部规范的对象。 Reference 对象 定义于 JSON Reference 且遵循相同的结构、行为和规则。
}

// Media 本质即为不一样 content_type 对应的数据结构定义
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 17:21 2024/7/19
type Media struct {
	Schema   *Schema              `json:"schema,omitempty"`   // 定义此媒体类型的结构。
	Example  string               `json:"example,omitempty"`  // 媒体类型的示例。示例对象应该符合此媒体类型的格式， 这里指定的example对象 object is mutually exclusive of the examples object. 而且如果引用的schema也包含示例，在这里指定的example值将会覆盖schema提供的示例。
	Examples map[string]*Example  `json:"examples,omitempty"` // 媒体类型的示例，每个媒体对象的值都应该匹配它对应的媒体类型的格式。 The examples object is mutually exclusive of the example object. 而且如果引用的schema也包含示例，在这里指定的example值将会覆盖schema提供的示例。
	Encoding map[string]*Encoding `json:"encoding,omitempty"` // 属性名与编码信息的映射。每个属性名必须存在于schema属性的key中，当媒体类型等于multipart或application/x-www-form-urlencoded时，编码对象信息仅适用于requestBody。
}

// Encoding 一个编码定义仅适用于一个结构属性
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 17:28 2024/7/19
type Encoding struct {
	ContentType   string             `json:"content_type,omitempty"`  // 对具体属性的 Content-Type的编码。默认值取决于属性的类型：application/octet-stream编码适用于binary格式的string；text/plain适用于其他原始值；application/json适用于object；对于array值类型的默认值取决于数组内元素的类型，默认值可以是明确的媒体类型(比如application/json), 或者通配符类型的媒体类型(比如image/*), 又或者是用分号分隔的两种媒体类型。
	Headers       map[string]*Header `json:"headers,omitempty"`       // 提供附加信息的请求头键值对映射。比如Content-Disposition、Content-Type各自描述了不同的信息而且在这里将会被忽略，如果请求体的媒体类型不是multipart，这个属性将会被忽略。
	Style         string             `json:"style,omitempty"`         // 描述一个属性根据它的类型将会被如何序列化。查看Parameter 对象的style属性可以得到更多详细信息。这个属性的行为与query参数相同，包括默认值的定义。如果请求体的媒体类型不是application/x-www-form-urlencoded，这个属性将会被忽略。
	Explode       bool               `json:"explode,omitempty"`       // 当这个值为true时，类型为array或object的属性值会为数组的每个元素或对象的每个键值对分开生成参数。这个属性对其他数据类型没有影响。当style为form时，这个属性的默认值是true，对于其他的style类型，这个属性的默认值是false。这个属性会被忽略如果请求体的媒体类型不是application/x-www-form-urlencoded。
	AllowReserved bool               `json:"allowReserved,omitempty"` // 决定此参数的值是否允许不使用%号编码使用定义于 RFC3986内的保留字符 :/?#[]@!$&'()*+,;=。 这个属性仅用于in的值是query时，此字段的默认值是false。 这个属性会被忽略如果请求体的媒体类型不是application/x-www-form-urlencoded。
}

// Header 对象除了以下改动之外与 Parameter 对象 一致：
//
// name 不能被指定，它在相应的 headers 映射中被指定。
// in 不能被指定，它隐含在 header 中。
// 所有被 location 影响的特性必须适合 header 中的一个 location，(比如 style)。
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 17:30 2024/7/19
type Header PathConfigParameter

// Example ...
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 17:24 2024/7/19
type Example struct {
	Summary       string `json:"summary,omitempty"`       // example 的简要描述。
	Description   string `json:"description,omitempty"`   // example 的详细描述。CommonMark syntax可以被用来呈现富文本格式.
	Value         any    `json:"value,omitempty"`         // 嵌入的字面量 example。 value 字段和 externalValue 字段是互斥的。无法使用 JSON 或 YAML 表示的媒体类型可以使用字符串值来表示。
	ExternalValue string `json:"externalValue,omitempty"` // 指向字面 example 的一个 URL。这提供了引用无法被包含在 JSON 或 YAML 文档中的 example。value 字段和 externalValue 字段是互斥的。
}

// Response 响应的数据结构
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 17:38 2024/7/19
type Response struct {
	Description string             `json:"description" required:"true"` // 必选. 对响应的简短描述。CommonMark syntax可以被用来呈现富文本格式.
	Headers     map[string]*Header `json:"headers,omitempty"`           // 映射HTTP头名称到其定义。RFC7230 规定了HTTP头名称不区分大小写。如果一个响应头使用"Content-Type"作为HTTP头名称，它会被忽略。
	Content     map[string]*Media  `json:"content,omitempty"`           // 一个包含描述预期响应负载的映射。使用 media type 或 media type range 作为键，以响应的描述作为值。当一个响应匹配多个键时，只有最明确的键才适用。比如：text/plain 会覆盖 text/*
	Ref         string             `json:"$ref,omitempty"`              // 引用描述
}

// Info 信息
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 16:10 2024/4/19
type Info struct {
	Description    string   `json:"description,omitempty"`           // 对应用的简短描述。 CommonMark syntax 可以被用来表示富文本呈现。
	Title          string   `json:"title,omitempty" required:"true"` // 必选. 应用的名称。
	TermsOfService string   `json:"termsOfService,omitempty"`        // 指向服务条款的 URL 地址，必须是 URL 地址格式。
	Contact        *Contact `json:"contact,omitempty,omitempty"`     // 联系方式
	License        *License `json:"license,omitempty"`               // 开源协议
	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,omitempty"`  // 人或组织的名称。
	Url   string `json:"url,omitempty"`   // 指向联系人信息的 URL 地址，必须是 URL 地址格式。
	Email string `json:"email,omitempty"` // 人或组织的 email 地址，必须是 email 地址格式
}

// License 开源协议
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 16:09 2024/4/19
type License struct {
	Name string `json:"name,omitempty"` // 开源协议名
	Url  string `json:"url,omitempty"`  // 开源协议地址
}

// ServerItem server 对象结构
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 14:18 2024/7/19
type ServerItem struct {
	Url         string                         `json:"url,omitempty" required:"true"` // 必选. 指向目标主机的 URL 地址。这个 URL 地址支持服务器变量而且可能是相对路径，表示主机路径是相对于本文档所在的路径。当一个变量被命名为类似{brackets}时需要替换此变量。
	Description string                         `json:"description,omitempty"`         // 一个可选的字符串，用来描述此 URL 地址。CommonMark syntax可以被用来呈现富文本格式.
	Variables   map[string]*ServerItemVariable `json:"variables,omitempty"`           // 当 url 中出现变量名的时候, 会从次变量中读取数据替换到url中. 变量名 -> 变量配置
}

// ServerItemVariable ...
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 14:22 2024/7/19
type ServerItemVariable struct {
	Default     string   `json:"default,omitempty"`     // 变量默认值
	Description string   `json:"description,omitempty"` // 变量描述
	Enum        []string `json:"enum,omitempty"`        // 变量枚举值
}

// TagItem 每一个标签数据结构
//
// Author : go_developer@163.com<白茶清欢>
//
// Date : 12:18 2024/7/19
type TagItem struct {
	Name        string `json:"name,omitempty"`        // 标签名称
	Description string `json:"description,omitempty"` // 标签描述
}