diff --git a/define/openapi.go b/define/openapi.go index fea8436..28e0e36 100644 --- a/define/openapi.go +++ b/define/openapi.go @@ -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"` // 标签描述 +} diff --git a/define/types.go b/define/types.go index a4eb807..86c48eb 100644 --- a/define/types.go +++ b/define/types.go @@ -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<张德满> diff --git a/parser.go b/parser.go new file mode 100644 index 0000000..409886a --- /dev/null +++ b/parser.go @@ -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() { + +}