// 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"` // 标签描述
}