From 458d33cba5fff276e458f7a8071ce20390075a9b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=99=BD=E8=8C=B6=E6=B8=85=E6=AC=A2?= Date: Fri, 19 Jul 2024 15:59:20 +0800 Subject: [PATCH 01/15] =?UTF-8?q?=E5=A2=9E=E5=8A=A0openapi=E6=96=87?= =?UTF-8?q?=E6=A1=A3=E5=9F=BA=E7=A1=80=E7=9A=84=E4=BF=A1=E6=81=AF=E5=AE=9A?= =?UTF-8?q?=E4=B9=89=20+=20parameter=E5=9F=BA=E7=A1=80=E5=AE=9A=E4=B9=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- define/openapi.go | 130 +++++++++++++++++++++++++++++++++++++++++++++- define/types.go | 34 ------------ parser.go | 23 ++++++++ 3 files changed, 152 insertions(+), 35 deletions(-) create mode 100644 parser.go 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() { + +} -- 2.36.6 From e71ff46d9640b25be0fa98ed23e57b15c88e5f12 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=99=BD=E8=8C=B6=E6=B8=85=E6=AC=A2?= Date: Fri, 19 Jul 2024 17:06:18 +0800 Subject: [PATCH 02/15] =?UTF-8?q?=E5=A2=9E=E5=8A=A0=E6=95=B0=E6=8D=AE?= =?UTF-8?q?=E7=BB=93=E6=9E=84=E7=9A=84=E5=AE=9A=E4=B9=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- define/openapi.go | 145 ++++++++++++++++++++++++++++++++++++---------- 1 file changed, 115 insertions(+), 30 deletions(-) diff --git a/define/openapi.go b/define/openapi.go index 28e0e36..3a29f5a 100644 --- a/define/openapi.go +++ b/define/openapi.go @@ -13,26 +13,73 @@ package define // // 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"` // 接口路径 -> 接口请求方法 -> 具体配置 + 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"` // 接口路径 -> 接口请求方法 -> 具体配置 } -// PathConfig 接口的具体配置 +// PathItemConfig 接口的具体配置 +// 描述对一个路径可执行的有效操作。 +// 依赖与 ACL constraints 的设置，一个Path Item可以是一个空对象， +// 文档的读者仍然可以看到这个路径，但是他们将无法了解到对这个路径可用的任何操作和参数。 // // 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"` // 请求体配置 +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 参数配置 @@ -41,28 +88,66 @@ type PathConfig struct { // // 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。 + 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 且遵循相同的结构、行为和规则。 } -// PathConfigParameterSchema ... +// Schema ... // // 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 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 { +} + +// 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"` // 只可被用于数组定义。表示数组是否被包裹（比如, ）或未被包裹（）。默认值是 false。此定义只在 type 为 array（位于 items 之上） 时生效。 } type RequestBody struct { -- 2.36.6 From 00939d3835fe25eba6c60a13d98500dc545c34c1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=99=BD=E8=8C=B6=E6=B8=85=E6=AC=A2?= Date: Fri, 19 Jul 2024 17:16:38 +0800 Subject: [PATCH 03/15] =?UTF-8?q?=E5=AE=8C=E5=96=84schema=E5=AF=B9?= =?UTF-8?q?=E8=B1=A1=E5=AE=9A=E4=B9=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- define/openapi.go | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/define/openapi.go b/define/openapi.go index 3a29f5a..4cc93ab 100644 --- a/define/openapi.go +++ b/define/openapi.go @@ -124,6 +124,23 @@ type Schema struct { // // 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 对象来帮助序列化、反序列化和校验 -- 2.36.6 From 7f47da66600b1896faaebde88e96ad681b9af4be Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=99=BD=E8=8C=B6=E6=B8=85=E6=AC=A2?= Date: Fri, 19 Jul 2024 17:34:27 +0800 Subject: [PATCH 04/15] =?UTF-8?q?=E5=AE=8C=E6=88=90requestBody=E5=AE=9A?= =?UTF-8?q?=E4=B9=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- define/openapi.go | 71 ++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 58 insertions(+), 13 deletions(-) diff --git a/define/openapi.go b/define/openapi.go index 4cc93ab..86546ed 100644 --- a/define/openapi.go +++ b/define/openapi.go @@ -57,19 +57,7 @@ type PathItemOperationConfig struct { 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 且遵循相同的结构、行为和规则。 + RequestBody *RequestBody `json:"requestBody"` // 可用于此操作的请求体。requestBody 只能被用于HTTP 1.1 规范 RFC7231 中明确定义了包含请求体的请求方法，在其他没有明确定义的请求方法中，requestBody的消费者应该应该忽略requestBody。 } // ExternalDocs 外部文档配置 @@ -167,7 +155,64 @@ type XML struct { Wrapped bool `json:"wrapped"` // 只可被用于数组定义。表示数组是否被包裹（比如, ）或未被包裹（）。默认值是 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"` // 对请求体的简要描述，可以包含使用示例，CommonMark syntax可以被用来呈现富文本格式 + Content map[string]*Media `json:"content"` // content_type => 相应数据描述的映射 必选. 请求体的内容。请求体的属性key是一个媒体类型或者媒体类型范围，值是对应媒体类型的示例数据。对于能匹配多个key的请求，定义更明确的请求会更优先被匹配。比如text/plain会覆盖text/*的定义。 + Ref string `json:"$ref"` // 一个允许引用规范内部的其他部分或外部规范的对象。 Reference 对象 定义于 JSON Reference 且遵循相同的结构、行为和规则。 +} + +// Media 本质即为不一样 content_type 对应的数据结构定义 +// +// Author : go_developer@163.com<白茶清欢> +// +// Date : 17:21 2024/7/19 +type Media struct { + Schema *Schema `json:"schema"` // 定义此媒体类型的结构。 + Example string `json:"example"` // 媒体类型的示例。示例对象应该符合此媒体类型的格式， 这里指定的example对象 object is mutually exclusive of the examples object. 而且如果引用的schema也包含示例，在这里指定的example值将会覆盖schema提供的示例。 + Examples map[string]*Example `json:"examples"` // 媒体类型的示例，每个媒体对象的值都应该匹配它对应的媒体类型的格式。 The examples object is mutually exclusive of the example object. 而且如果引用的schema也包含示例，在这里指定的example值将会覆盖schema提供的示例。 + Encoding map[string]*Encoding `json:"encoding"` // 属性名与编码信息的映射。每个属性名必须存在于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"` // 对具体属性的 Content-Type的编码。默认值取决于属性的类型：application/octet-stream编码适用于binary格式的string；text/plain适用于其他原始值；application/json适用于object；对于array值类型的默认值取决于数组内元素的类型，默认值可以是明确的媒体类型(比如application/json), 或者通配符类型的媒体类型(比如image/*), 又或者是用分号分隔的两种媒体类型。 + Headers map[string]*Header `json:"headers"` // 提供附加信息的请求头键值对映射。比如Content-Disposition、Content-Type各自描述了不同的信息而且在这里将会被忽略，如果请求体的媒体类型不是multipart，这个属性将会被忽略。 + Style string `json:"style"` // 描述一个属性根据它的类型将会被如何序列化。查看Parameter 对象的style属性可以得到更多详细信息。这个属性的行为与query参数相同，包括默认值的定义。如果请求体的媒体类型不是application/x-www-form-urlencoded，这个属性将会被忽略。 + Explode bool `json:"explode"` // 当这个值为true时，类型为array或object的属性值会为数组的每个元素或对象的每个键值对分开生成参数。这个属性对其他数据类型没有影响。当style为form时，这个属性的默认值是true，对于其他的style类型，这个属性的默认值是false。这个属性会被忽略如果请求体的媒体类型不是application/x-www-form-urlencoded。 + AllowReserved bool `json:"allowReserved"` // 决定此参数的值是否允许不使用%号编码使用定义于 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"` // example 的简要描述。 + Description string `json:"description"` // example 的详细描述。CommonMark syntax可以被用来呈现富文本格式. + Value any `json:"value"` // 嵌入的字面量 example。 value 字段和 externalValue 字段是互斥的。无法使用 JSON 或 YAML 表示的媒体类型可以使用字符串值来表示。 + ExternalValue string `json:"externalValue"` // 指向字面 example 的一个 URL。这提供了引用无法被包含在 JSON 或 YAML 文档中的 example。value 字段和 externalValue 字段是互斥的。 } // Info 信息 -- 2.36.6 From d0d751b44fbf0d05b8ade0cc6e01e0d94a62e940 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=99=BD=E8=8C=B6=E6=B8=85=E6=AC=A2?= Date: Fri, 19 Jul 2024 17:47:06 +0800 Subject: [PATCH 05/15] =?UTF-8?q?=E5=AE=8C=E6=88=90=E4=B8=80=E7=89=88=20Op?= =?UTF-8?q?tion=E5=AE=9A=E4=B9=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- define/openapi.go | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/define/openapi.go b/define/openapi.go index 86546ed..eda4e85 100644 --- a/define/openapi.go +++ b/define/openapi.go @@ -15,7 +15,7 @@ package define type OpenapiDoc struct { Openapi string `json:"openapi" required:"true"` // 必选. 这个字符串必须是开放 API 规范版本号提到的符合语义化版本号规范的版本号。openapi字段应该被工具或者客户端用来解释 OpenAPI 文档. Info *Info `json:"info" required:"true"` // 必选。此字段提供 API 相关的元数据。相关工具可能需要这个字段。 - Servers []any `json:"servers"` // 服务环境 + Servers []*ServerItem `json:"servers"` // 服务环境 Tags []TagItem `json:"tags"` // 全部标签列表 Paths map[string]map[string]*PathItemConfig `json:"paths"` // 接口路径 -> 接口请求方法 -> 具体配置 } @@ -58,6 +58,11 @@ type PathItemOperationConfig struct { OperationID string `json:"operationId"` // 用于标识此操作的唯一字符串，这个id在此API内包含的所有操作中必须是唯一的。相关的工具和库可能会使用此operationId来唯一的标识一个操作，因此推荐在命名时符合一般的编程命名习惯 Parameters []*PathConfigParameter `json:"parameters"` // 定义可用于此操作的参数列表，如果一个同名的参数已经存在于 Path Item，那么这里的定义会覆盖它但是不能移除上面的定义。这个列表不允许包含重复的参数，参数的唯一性由 name 和 location 的组合来确定。这个列表可以使用 Reference 对象 来连接定义于 OpenAPI 对象 components/parameters 的参数。 RequestBody *RequestBody `json:"requestBody"` // 可用于此操作的请求体。requestBody 只能被用于HTTP 1.1 规范 RFC7231 中明确定义了包含请求体的请求方法，在其他没有明确定义的请求方法中，requestBody的消费者应该应该忽略requestBody。 + Responses map[string]*Response `json:"responses"` // 描述一个操作可能发生的响应的响应码与响应包含的响应体的对象。default字段可以用来标记一个响应适用于其他未被规范明确定义的HTTP响应码的默认响应。一个Responses 对象必须至少包含一个响应码，而且是成功的响应。 + Callbacks map[string]any `json:"callbacks"` // 一组相对于父操作的可能出现的回调映射，映射中的每一个键都唯一的映射一个 Callback 对象 + Deprecated bool `json:"deprecated"` // 声明此操作已经被废弃，使用者应该尽量避免使用此操作，默认的值是 false。 + Security any `json:"security"` // 声明那种安全机制可用于此操作。这个列表可以包含多种可用于此操作的安全需求对象，但是在认证一个请求时应该仅使用其中一种。这里的定义会覆盖任何在顶层 security 中的安全声明，因此可以声明一个空数组来变相的移除顶层的安全声明。 + Servers []*ServerItem `json:"servers"` // 一个可用于此操作的额外的 server 数组，这里的定义会覆盖 Path Item 对象 或 顶层的定义。 } // ExternalDocs 外部文档配置 @@ -215,6 +220,18 @@ type Example struct { ExternalValue string `json:"externalValue"` // 指向字面 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"` // 必选. 对响应的简短描述。CommonMark syntax可以被用来呈现富文本格式. + Headers map[string]*Header `json:"headers"` // 映射HTTP头名称到其定义。RFC7230 规定了HTTP头名称不区分大小写。如果一个响应头使用"Content-Type"作为HTTP头名称，它会被忽略。 + Content map[string]*Media `json:"content"` // 一个包含描述预期响应负载的映射。使用 media type 或 media type range 作为键，以响应的描述作为值。当一个响应匹配多个键时，只有最明确的键才适用。比如：text/plain 会覆盖 text/* + Ref string `json:"$ref"` // 引用描述 +} + // Info 信息 // // Author : go_developer@163.com<白茶清欢> -- 2.36.6 From c7765d57c1885e8aa3862113e80542b5d725bf75 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=99=BD=E8=8C=B6=E6=B8=85=E6=AC=A2?= Date: Fri, 19 Jul 2024 18:01:14 +0800 Subject: [PATCH 06/15] =?UTF-8?q?=E5=A2=9E=E5=8A=A0=E5=8D=95=E5=85=83?= =?UTF-8?q?=E6=B5=8B=E8=AF=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- define/openapi.go | 6 +- parser_test.go | 237 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 240 insertions(+), 3 deletions(-) create mode 100644 parser_test.go diff --git a/define/openapi.go b/define/openapi.go index eda4e85..9f419ad 100644 --- a/define/openapi.go +++ b/define/openapi.go @@ -39,9 +39,9 @@ type PathItemConfig struct { 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 操作。 + Head *PathItemOperationConfig `json:"head"` // 定义适用于此路径的 HEAD 操作。 + Patch *PathItemOperationConfig `json:"patch"` // 定义适用于此路径的 PATCH 操作。 + Trace *PathItemOperationConfig `json:"trace"` // 定义适用于此路径的 TRACE 操作。 Parameters []*PathConfigParameter `json:"parameters"` // 参数列表, 对于所有请求生效 } diff --git a/parser_test.go b/parser_test.go new file mode 100644 index 0000000..98b0df4 --- /dev/null +++ b/parser_test.go @@ -0,0 +1,237 @@ +// Package api_doc ... +// +// Description : api_doc ... +// +// Author : go_developer@163.com<白茶清欢> +// +// Date : 2024-07-19 17:52 +package api_doc + +import ( + "encoding/json" + "fmt" + "git.zhangdeman.cn/gateway/api-doc/define" + "testing" +) + +// Test_parser_Openapi3 测试数据结构定义正确性 +// +// Author : go_developer@163.com<白茶清欢> +// +// Date : 17:55 2024/7/19 +func Test_parser_Openapi3(t *testing.T) { + testData := `{ + "openapi": "3.0.1", + "info": { + "title": "测试", + "description": "测试", + "contact": { + "name": "白茶", + "url": "http://www.baidu.com", + "email": "go@email.com" + }, + "license": { + "name": "Apache-2.0", + "url": "https://www.apache.org/licenses/LICENSE-2.0.txt" + }, + "version": "" + }, + "servers": [ + { + "url": "http://www.baidu.com/" + } + ], + "paths": { + "/test": { + "post": { + "tags": [ + "测试接口生成" + ], + "summary": "测试接口", + "description": "测试接口", + "requestBody": { + "description": "参数结构", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/test.jsonBody" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "返回数据", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/test.200.output" + } + } + } + } + }, + "x-codegen-request-body-name": "jsonBody" + } + } + }, + "components": { + "schemas": { + "object_map": { + "type": "object" + }, + "test.200.output": { + "type": "object", + "properties": { + "nick_name": { + "type": "string", + "description": "姓名" + }, + "obj": { + "type": "object", + "description": "测试返回生成map", + "allOf": [ + { + "$ref": "#/components/schemas/object_map" + } + ] + }, + "person": { + "type": "object", + "description": "参数描述", + "allOf": [ + { + "$ref": "#/components/schemas/test.200.output.person" + } + ] + } + }, + "format": "map[string]any" + }, + "test.200.output.person": { + "type": "object", + "properties": { + "nick_name": { + "type": "string", + "description": "昵称" + } + }, + "format": "map[string]any" + }, + "test.jsonBody": { + "required": [ + "age", + "name" + ], + "type": "object", + "properties": { + "age": { + "type": "integer", + "description": "年龄" + }, + "name": { + "type": "string", + "description": "姓名" + }, + "obj": { + "type": "object", + "description": "测试global_map", + "allOf": [ + { + "$ref": "#/components/schemas/object_map" + } + ] + }, + "person": { + "type": "object", + "description": "参数描述", + "allOf": [ + { + "$ref": "#/components/schemas/test.jsonBody.person" + } + ] + }, + "test_list": { + "type": "array", + "description": "参数描述", + "items": { + "$ref": "#/components/schemas/test.jsonBody.test_list.item" + } + } + }, + "format": "map[string]any" + }, + "test.jsonBody.person": { + "type": "object", + "properties": { + "job": { + "type": "object", + "description": "参数描述", + "allOf": [ + { + "$ref": "#/components/schemas/test.jsonBody.person.job" + } + ] + }, + "sex": { + "type": "string", + "description": "性别" + } + }, + "format": "map[string]any" + }, + "test.jsonBody.person.job": { + "type": "object", + "properties": { + "list": { + "type": "array", + "description": "性别", + "items": { + "type": "string" + } + }, + "test": { + "type": "integer", + "description": "测试工作" + }, + "year": { + "type": "array", + "description": "年份", + "items": { + "type": "integer" + } + } + }, + "format": "map[string]any" + }, + "test.jsonBody.test_list.item": { + "required": [ + "age", + "name" + ], + "type": "object", + "properties": { + "age": { + "type": "integer", + "description": "年龄" + }, + "name": { + "type": "string", + "description": "年龄" + } + }, + "format": "map[string]any" + } + } + }, + "x-original-swagger-version": "2.0" +}` + var data define.OpenapiDoc + err := json.Unmarshal([]byte(testData), &data) + if nil != err { + fmt.Println("解析失败 : " + err.Error()) + } else { + fmt.Println("解析成功") + } +} -- 2.36.6 From 93316f739f080e72faa0a91b69c12e2eac465838 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=99=BD=E8=8C=B6=E6=B8=85=E6=AC=A2?= Date: Fri, 19 Jul 2024 18:08:22 +0800 Subject: [PATCH 07/15] =?UTF-8?q?=E8=B0=83=E6=95=B4path=E6=95=B0=E6=8D=AE?= =?UTF-8?q?=E7=BB=93=E6=9E=84=E5=AE=9A=E4=B9=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- define/openapi.go | 47 ++++++++++++++++++++++++++++------------------- 1 file changed, 28 insertions(+), 19 deletions(-) diff --git a/define/openapi.go b/define/openapi.go index 9f419ad..e89ba04 100644 --- a/define/openapi.go +++ b/define/openapi.go @@ -13,11 +13,27 @@ package define // // 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 []*ServerItem `json:"servers"` // 服务环境 - Tags []TagItem `json:"tags"` // 全部标签列表 - Paths map[string]map[string]*PathItemConfig `json:"paths"` // 接口路径 -> 接口请求方法 -> 具体配置 + Openapi string `json:"openapi" required:"true"` // 必选. 这个字符串必须是开放 API 规范版本号提到的符合语义化版本号规范的版本号。openapi字段应该被工具或者客户端用来解释 OpenAPI 文档. + Info *Info `json:"info" required:"true"` // 必选。此字段提供 API 相关的元数据。相关工具可能需要这个字段。 + Servers []*ServerItem `json:"servers"` // 服务环境 + Tags []TagItem `json:"tags"` // 全部标签列表 + Paths map[string]*PathConfig `json:"paths"` // 接口路径 -> 接口请求方法 -> 具体配置 +} + +// PathConfig ... +// +// Author : go_developer@163.com<白茶清欢> +// +// Date : 18:06 2024/7/19 +type PathConfig struct { + 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 *PathItemOperationConfig `json:"head"` // 定义适用于此路径的 HEAD 操作。 + Patch *PathItemOperationConfig `json:"patch"` // 定义适用于此路径的 PATCH 操作。 + Trace *PathItemOperationConfig `json:"trace"` // 定义适用于此路径的 TRACE 操作。 } // PathItemConfig 接口的具体配置 @@ -29,20 +45,13 @@ type OpenapiDoc struct { // // 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 *PathItemOperationConfig `json:"head"` // 定义适用于此路径的 HEAD 操作。 - Patch *PathItemOperationConfig `json:"patch"` // 定义适用于此路径的 PATCH 操作。 - Trace *PathItemOperationConfig `json:"trace"` // 定义适用于此路径的 TRACE 操作。 - Parameters []*PathConfigParameter `json:"parameters"` // 参数列表, 对于所有请求生效 + 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"` // 参数列表, 对于所有请求生效 } // PathItemOperationConfig 描述对路径的某个操作。 -- 2.36.6 From 6642b9bceffa9a0be19ee25591174ba0e8e4ef09 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=99=BD=E8=8C=B6=E6=B8=85=E6=AC=A2?= Date: Fri, 19 Jul 2024 18:28:51 +0800 Subject: [PATCH 08/15] =?UTF-8?q?=E6=9B=B4=E6=96=B0=E5=8D=95=E5=85=83?= =?UTF-8?q?=E6=B5=8B=E8=AF=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- parser_test.go | 213 ++----------------------------------------------- 1 file changed, 5 insertions(+), 208 deletions(-) diff --git a/parser_test.go b/parser_test.go index 98b0df4..25b76b7 100644 --- a/parser_test.go +++ b/parser_test.go @@ -11,6 +11,8 @@ import ( "encoding/json" "fmt" "git.zhangdeman.cn/gateway/api-doc/define" + "os" + "os/user" "testing" ) @@ -20,215 +22,10 @@ import ( // // Date : 17:55 2024/7/19 func Test_parser_Openapi3(t *testing.T) { - testData := `{ - "openapi": "3.0.1", - "info": { - "title": "测试", - "description": "测试", - "contact": { - "name": "白茶", - "url": "http://www.baidu.com", - "email": "go@email.com" - }, - "license": { - "name": "Apache-2.0", - "url": "https://www.apache.org/licenses/LICENSE-2.0.txt" - }, - "version": "" - }, - "servers": [ - { - "url": "http://www.baidu.com/" - } - ], - "paths": { - "/test": { - "post": { - "tags": [ - "测试接口生成" - ], - "summary": "测试接口", - "description": "测试接口", - "requestBody": { - "description": "参数结构", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/test.jsonBody" - } - } - }, - "required": true - }, - "responses": { - "200": { - "description": "返回数据", - "content": { - "*/*": { - "schema": { - "$ref": "#/components/schemas/test.200.output" - } - } - } - } - }, - "x-codegen-request-body-name": "jsonBody" - } - } - }, - "components": { - "schemas": { - "object_map": { - "type": "object" - }, - "test.200.output": { - "type": "object", - "properties": { - "nick_name": { - "type": "string", - "description": "姓名" - }, - "obj": { - "type": "object", - "description": "测试返回生成map", - "allOf": [ - { - "$ref": "#/components/schemas/object_map" - } - ] - }, - "person": { - "type": "object", - "description": "参数描述", - "allOf": [ - { - "$ref": "#/components/schemas/test.200.output.person" - } - ] - } - }, - "format": "map[string]any" - }, - "test.200.output.person": { - "type": "object", - "properties": { - "nick_name": { - "type": "string", - "description": "昵称" - } - }, - "format": "map[string]any" - }, - "test.jsonBody": { - "required": [ - "age", - "name" - ], - "type": "object", - "properties": { - "age": { - "type": "integer", - "description": "年龄" - }, - "name": { - "type": "string", - "description": "姓名" - }, - "obj": { - "type": "object", - "description": "测试global_map", - "allOf": [ - { - "$ref": "#/components/schemas/object_map" - } - ] - }, - "person": { - "type": "object", - "description": "参数描述", - "allOf": [ - { - "$ref": "#/components/schemas/test.jsonBody.person" - } - ] - }, - "test_list": { - "type": "array", - "description": "参数描述", - "items": { - "$ref": "#/components/schemas/test.jsonBody.test_list.item" - } - } - }, - "format": "map[string]any" - }, - "test.jsonBody.person": { - "type": "object", - "properties": { - "job": { - "type": "object", - "description": "参数描述", - "allOf": [ - { - "$ref": "#/components/schemas/test.jsonBody.person.job" - } - ] - }, - "sex": { - "type": "string", - "description": "性别" - } - }, - "format": "map[string]any" - }, - "test.jsonBody.person.job": { - "type": "object", - "properties": { - "list": { - "type": "array", - "description": "性别", - "items": { - "type": "string" - } - }, - "test": { - "type": "integer", - "description": "测试工作" - }, - "year": { - "type": "array", - "description": "年份", - "items": { - "type": "integer" - } - } - }, - "format": "map[string]any" - }, - "test.jsonBody.test_list.item": { - "required": [ - "age", - "name" - ], - "type": "object", - "properties": { - "age": { - "type": "integer", - "description": "年龄" - }, - "name": { - "type": "string", - "description": "年龄" - } - }, - "format": "map[string]any" - } - } - }, - "x-original-swagger-version": "2.0" -}` + current, _ := user.Current() + byteData, _ := os.ReadFile(current.HomeDir + "/Downloads/test-openapi-doc.json") var data define.OpenapiDoc - err := json.Unmarshal([]byte(testData), &data) + err := json.Unmarshal(byteData, &data) if nil != err { fmt.Println("解析失败 : " + err.Error()) } else { -- 2.36.6 From 0dd07307b109ceb2db5d650cb98f89f6abe26c78 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=99=BD=E8=8C=B6=E6=B8=85=E6=AC=A2?= Date: Fri, 19 Jul 2024 20:52:33 +0800 Subject: [PATCH 09/15] update go sum --- go.sum | 8 -------- 1 file changed, 8 deletions(-) diff --git a/go.sum b/go.sum index 91960cd..99d3741 100644 --- a/go.sum +++ b/go.sum @@ -1,11 +1,3 @@ -git.zhangdeman.cn/zhangdeman/consts v0.0.0-20240422030654-fc4470a2cebc h1:1fgPDwrLyvRP5A5PAoog3RtRQZ6c7JFtl+ZJmFEqyQQ= -git.zhangdeman.cn/zhangdeman/consts v0.0.0-20240422030654-fc4470a2cebc/go.mod h1:IXXaZkb7vGzGnGM5RRWrASAuwrVSNxuoe0DmeXx5g6k= -git.zhangdeman.cn/zhangdeman/consts v0.0.0-20240425080806-c101cbfe4cad h1:hOmxPRzrD6tDPjZH8lVBuSkz3WXr7j/q2aD9AvEGTFg= -git.zhangdeman.cn/zhangdeman/consts v0.0.0-20240425080806-c101cbfe4cad/go.mod h1:IXXaZkb7vGzGnGM5RRWrASAuwrVSNxuoe0DmeXx5g6k= -git.zhangdeman.cn/zhangdeman/consts v0.0.0-20240425083843-f40760f6ee22 h1:98cFHVl4z4+AboA3r6UOVYKDOLgANePFjnItZ3FufvY= -git.zhangdeman.cn/zhangdeman/consts v0.0.0-20240425083843-f40760f6ee22/go.mod h1:IXXaZkb7vGzGnGM5RRWrASAuwrVSNxuoe0DmeXx5g6k= -git.zhangdeman.cn/zhangdeman/consts v0.0.0-20240425085343-09fdf2f01e4f h1:bbn19GoW7ScVB6BybUthRqsc4hxc0EqmGyCICXlXkr8= -git.zhangdeman.cn/zhangdeman/consts v0.0.0-20240425085343-09fdf2f01e4f/go.mod h1:IXXaZkb7vGzGnGM5RRWrASAuwrVSNxuoe0DmeXx5g6k= git.zhangdeman.cn/zhangdeman/consts v0.0.0-20240425091616-00e0a924efcd h1:RBFDiEMI97fuzpyb5HBN4lu3UXTAGYo6nlGhV2gWq5U= git.zhangdeman.cn/zhangdeman/consts v0.0.0-20240425091616-00e0a924efcd/go.mod h1:IXXaZkb7vGzGnGM5RRWrASAuwrVSNxuoe0DmeXx5g6k= git.zhangdeman.cn/zhangdeman/easymap v0.0.0-20240311030808-e2a2e6a3c211 h1:I/wOsRpCSRkU9vo1u703slQsmK0wnNeZzsWQOGtIAG0= -- 2.36.6 From dde831540468f253759b8fb27643ff14304c5cb4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=99=BD=E8=8C=B6=E6=B8=85=E6=AC=A2?= Date: Fri, 19 Jul 2024 21:18:20 +0800 Subject: [PATCH 10/15] =?UTF-8?q?=E4=BF=AE=E5=A4=8Dproperty=E5=AE=9A?= =?UTF-8?q?=E4=B9=89=E9=97=AE=E9=A2=98?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- define/openapi.go | 120 +++++++++++++++++++++++----------------------- 1 file changed, 60 insertions(+), 60 deletions(-) diff --git a/define/openapi.go b/define/openapi.go index e89ba04..f9062be 100644 --- a/define/openapi.go +++ b/define/openapi.go @@ -13,11 +13,11 @@ package define // // 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 []*ServerItem `json:"servers"` // 服务环境 - Tags []TagItem `json:"tags"` // 全部标签列表 - Paths map[string]*PathConfig `json:"paths"` // 接口路径 -> 接口请求方法 -> 具体配置 + Openapi string `json:"openapi" required:"true"` // 必选. 这个字符串必须是开放 API 规范版本号提到的符合语义化版本号规范的版本号。openapi字段应该被工具或者客户端用来解释 OpenAPI 文档. + Info *Info `json:"info,omitempty" required:"true"` // 必选。此字段提供 API 相关的元数据。相关工具可能需要这个字段。 + Servers []*ServerItem `json:"servers"` // 服务环境 + Tags []*TagItem `json:"tags"` // 全部标签列表 + Paths map[string]*PathConfig `json:"paths"` // 接口路径 -> 接口请求方法 -> 具体配置 } // PathConfig ... @@ -26,14 +26,14 @@ type OpenapiDoc struct { // // Date : 18:06 2024/7/19 type PathConfig struct { - 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 *PathItemOperationConfig `json:"head"` // 定义适用于此路径的 HEAD 操作。 - Patch *PathItemOperationConfig `json:"patch"` // 定义适用于此路径的 PATCH 操作。 - Trace *PathItemOperationConfig `json:"trace"` // 定义适用于此路径的 TRACE 操作。 + 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 操作。 } // PathItemConfig 接口的具体配置 @@ -45,13 +45,12 @@ type PathConfig struct { // // 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"` // 参数列表, 对于所有请求生效 + 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 描述对路径的某个操作。 @@ -60,18 +59,18 @@ type PathItemConfig struct { // // 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 *RequestBody `json:"requestBody"` // 可用于此操作的请求体。requestBody 只能被用于HTTP 1.1 规范 RFC7231 中明确定义了包含请求体的请求方法，在其他没有明确定义的请求方法中，requestBody的消费者应该应该忽略requestBody。 - Responses map[string]*Response `json:"responses"` // 描述一个操作可能发生的响应的响应码与响应包含的响应体的对象。default字段可以用来标记一个响应适用于其他未被规范明确定义的HTTP响应码的默认响应。一个Responses 对象必须至少包含一个响应码，而且是成功的响应。 - Callbacks map[string]any `json:"callbacks"` // 一组相对于父操作的可能出现的回调映射，映射中的每一个键都唯一的映射一个 Callback 对象 - Deprecated bool `json:"deprecated"` // 声明此操作已经被废弃，使用者应该尽量避免使用此操作，默认的值是 false。 - Security any `json:"security"` // 声明那种安全机制可用于此操作。这个列表可以包含多种可用于此操作的安全需求对象，但是在认证一个请求时应该仅使用其中一种。这里的定义会覆盖任何在顶层 security 中的安全声明，因此可以声明一个空数组来变相的移除顶层的安全声明。 - Servers []*ServerItem `json:"servers"` // 一个可用于此操作的额外的 server 数组，这里的定义会覆盖 Path Item 对象 或 顶层的定义。 + 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.o,omitempty"` // 声明那种安全机制可用于此操作。这个列表可以包含多种可用于此操作的安全需求对象，但是在认证一个请求时应该仅使用其中一种。这里的定义会覆盖任何在顶层 security 中的安全声明，因此可以声明一个空数组来变相的移除顶层的安全声明。 + Servers []*ServerItem `json:"servers,omitempty"` // 一个可用于此操作的额外的 server 数组，这里的定义会覆盖 Path Item 对象 或 顶层的定义。 } // ExternalDocs 外部文档配置 @@ -90,17 +89,17 @@ type ExternalDocs struct { // // 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 且遵循相同的结构、行为和规则。 + 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"` // 描述根据参数值类型的不同如何序列化参数。默认值为（基于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 ... @@ -109,15 +108,15 @@ type PathConfigParameter struct { // // 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"` // 数据字段 => 数据规则 + Nullable bool `json:"nullable"` // 对于定义的schema，允许发送 null 值。默认值是 false. + Discriminator *SchemaDiscriminator `json:"discriminator,omitempty"` // 说白了, 就是一个字段可能是不同的数据结构。。。 + 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,omitempty"` // 这只能用于 properties schemas，在 root schemas 中没有效果。 + ExternalDocs *ExternalDocs `json:"externalDocs,omitempty"` // 此 schema 附加的外部文档。 + Example string `json:"example,omitempty"` // 一个用于示范此 schema实例的示例，可以是任意格式。为了表达无法用 JSON 或 YAML 格式呈现的示例，可以使用 string 类型的值，且在必要的地方需要使用字符转义。 + Deprecated bool `json:"deprecated"` // 表示一个 schema 是废弃的，应该逐渐被放弃使用。默认值是 false. + Properties map[string]*Property `json:"properties,omitempty"` // 数据字段 => 数据规则 } // Property 是从 JSON Schema 提取出来的，但是做了一些调整以适应 OpenAPI Specification。 @@ -126,14 +125,15 @@ type Schema struct { // // 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。 + 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,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。 + Properties map[string]*Property `json:"properties,omitempty"` // type = object 时, 定义对象属性 } // PropertyXOf ... -- 2.36.6 From 11bf768221edcbff62e4d244fffaf22861b8d069 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=99=BD=E8=8C=B6=E6=B8=85=E6=AC=A2?= Date: Fri, 19 Jul 2024 21:34:12 +0800 Subject: [PATCH 11/15] =?UTF-8?q?=E5=A2=9E=E5=8A=A0=E6=95=B0=E6=8D=AE?= =?UTF-8?q?=E7=BB=93=E6=9E=84=E5=B1=9E=E6=80=A7=E5=AE=9A=E4=B9=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- define/openapi.go | 39 +++++++++++++++++++++++++-------------- 1 file changed, 25 insertions(+), 14 deletions(-) diff --git a/define/openapi.go b/define/openapi.go index f9062be..e53ebf3 100644 --- a/define/openapi.go +++ b/define/openapi.go @@ -13,11 +13,21 @@ package define // // 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"` // 服务环境 - Tags []*TagItem `json:"tags"` // 全部标签列表 - Paths map[string]*PathConfig `json:"paths"` // 接口路径 -> 接口请求方法 -> 具体配置 + 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 ... @@ -125,15 +135,16 @@ type Schema struct { // // 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,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。 - Properties map[string]*Property `json:"properties,omitempty"` // type = object 时, 定义对象属性 + 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,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 时, 定义对象属性 } // PropertyXOf ... -- 2.36.6 From 1f5544a0aff68c0a625329830e1dfab34e14aa9c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=99=BD=E8=8C=B6=E6=B8=85=E6=AC=A2?= Date: Fri, 19 Jul 2024 21:35:22 +0800 Subject: [PATCH 12/15] =?UTF-8?q?=E5=B1=9E=E6=80=A7=E5=A2=9E=E5=8A=A0?= =?UTF-8?q?=E6=9E=9A=E4=B8=BE=E5=80=BC=E5=AE=9A=E4=B9=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- define/openapi.go | 1 + 1 file changed, 1 insertion(+) diff --git a/define/openapi.go b/define/openapi.go index e53ebf3..786fc12 100644 --- a/define/openapi.go +++ b/define/openapi.go @@ -137,6 +137,7 @@ type Schema struct { type Property struct { Type string `json:"type"` // 数据类型, swagger本身的定义 Format string `json:"format"` // 对应编程语言中的数据类型描述 + Enum []any `json:"enum,omitempty"` // 枚举值列表 Default any `json:"default"` // 默认值 : 不同于 JSON Schema，这个值必须符合定义与相同级别的 Schema 对象 中定义的类型，比如 type 是 string，那么 default 可以是 "foo" 但不能是 1。 Description string `json:"description"` // 数据描述, CommonMark syntax可以被用来呈现富文本格式. AllOf []*PropertyXOf `json:"allOf,omitempty"` // type 是一个对象, allOf 指向对象描述 -- 2.36.6 From aa1625c4e7caa8bf4755b882bfd5d7ae4c6f827c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=99=BD=E8=8C=B6=E6=B8=85=E6=AC=A2?= Date: Fri, 19 Jul 2024 21:43:24 +0800 Subject: [PATCH 13/15] =?UTF-8?q?property=E5=A2=9E=E5=8A=A0ref=E5=B1=9E?= =?UTF-8?q?=E6=80=A7?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- define/openapi.go | 1 + 1 file changed, 1 insertion(+) diff --git a/define/openapi.go b/define/openapi.go index 786fc12..f740fb8 100644 --- a/define/openapi.go +++ b/define/openapi.go @@ -146,6 +146,7 @@ type Property struct { 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 ... -- 2.36.6 From 3895be6e1568d407100a3296e1e0cf4b9055e094 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=99=BD=E8=8C=B6=E6=B8=85=E6=AC=A2?= Date: Fri, 19 Jul 2024 21:55:12 +0800 Subject: [PATCH 14/15] =?UTF-8?q?schema=E5=A2=9E=E5=8A=A0required,=20?= =?UTF-8?q?=E4=BB=A3=E8=A1=A8=E5=BF=85=E4=BC=A0=E5=B1=9E=E6=80=A7=E5=88=97?= =?UTF-8?q?=E8=A1=A8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- define/openapi.go | 1 + 1 file changed, 1 insertion(+) diff --git a/define/openapi.go b/define/openapi.go index f740fb8..76ee6e8 100644 --- a/define/openapi.go +++ b/define/openapi.go @@ -127,6 +127,7 @@ type Schema struct { Example string `json:"example,omitempty"` // 一个用于示范此 schema实例的示例，可以是任意格式。为了表达无法用 JSON 或 YAML 格式呈现的示例，可以使用 string 类型的值，且在必要的地方需要使用字符转义。 Deprecated bool `json:"deprecated"` // 表示一个 schema 是废弃的，应该逐渐被放弃使用。默认值是 false. Properties map[string]*Property `json:"properties,omitempty"` // 数据字段 => 数据规则 + Required []string `json:"required,omitempty"` // 必传属性列表 } // Property 是从 JSON Schema 提取出来的，但是做了一些调整以适应 OpenAPI Specification。 -- 2.36.6 From bef28089bdc3c7bbaf9a63d06bd459c1dd48d951 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=99=BD=E8=8C=B6=E6=B8=85=E6=AC=A2?= Date: Fri, 19 Jul 2024 22:00:45 +0800 Subject: [PATCH 15/15] =?UTF-8?q?schema=20=E5=A2=9E=E5=8A=A0=20type/enum?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- define/openapi.go | 2 ++ 1 file changed, 2 insertions(+) diff --git a/define/openapi.go b/define/openapi.go index 76ee6e8..462619d 100644 --- a/define/openapi.go +++ b/define/openapi.go @@ -128,6 +128,8 @@ type Schema struct { Deprecated bool `json:"deprecated"` // 表示一个 schema 是废弃的，应该逐渐被放弃使用。默认值是 false. Properties map[string]*Property `json:"properties,omitempty"` // 数据字段 => 数据规则 Required []string `json:"required,omitempty"` // 必传属性列表 + Enum []any `json:"enum,omitempty"` // 枚举值列表 + Type string `json:"type"` // 类型 } // Property 是从 JSON Schema 提取出来的，但是做了一些调整以适应 OpenAPI Specification。 -- 2.36.6