From f885f61f620bcbe198874ddf68fe709b8d2962ef Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=99=BD=E8=8C=B6=E6=B8=85=E6=AC=A2?= Date: Mon, 10 Feb 2025 11:22:40 +0800 Subject: [PATCH] =?UTF-8?q?=E4=BC=98=E5=8C=96openapi=E6=96=87=E6=A1=A3?= =?UTF-8?q?=E6=95=B0=E6=8D=AE=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 | 74 +++++++++++++++++++++++------------------------ parser_test.go | 2 +- 2 files changed, 38 insertions(+), 38 deletions(-) diff --git a/define/openapi.go b/define/openapi.go index 3aa863b..b90ba1f 100644 --- a/define/openapi.go +++ b/define/openapi.go @@ -119,14 +119,14 @@ type PathConfigParameter struct { // // Date : 12:32 2024/7/19 type Schema struct { - Nullable bool `json:"nullable"` // 对于定义的schema，允许发送 null 值。默认值是 false. + Nullable bool `json:"nullable,omitempty"` // 对于定义的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。 + 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 string `json:"example,omitempty"` // 一个用于示范此 schema实例的示例，可以是任意格式。为了表达无法用 JSON 或 YAML 格式呈现的示例，可以使用 string 类型的值，且在必要的地方需要使用字符转义。 - Deprecated bool `json:"deprecated"` // 表示一个 schema 是废弃的，应该逐渐被放弃使用。默认值是 false. + Deprecated bool `json:"deprecated,omitempty"` // 表示一个 schema 是废弃的，应该逐渐被放弃使用。默认值是 false. Properties map[string]*Property `json:"properties,omitempty"` // 数据字段 => 数据规则 Required []string `json:"required,omitempty"` // 必传属性列表 Enum []any `json:"enum,omitempty"` // 枚举值列表 @@ -205,10 +205,10 @@ type RequestBody struct { // // 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。 + 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 一个编码定义仅适用于一个结构属性 @@ -217,11 +217,11 @@ type Media struct { // // 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。 + 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 对象 一致： @@ -241,10 +241,10 @@ type Header PathConfigParameter // // 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 字段是互斥的。 + 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 响应的数据结构 @@ -253,10 +253,10 @@ type Example struct { // // 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"` // 引用描述 + Description string `json:"description,omitempty"` // 必选. 对响应的简短描述。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 信息 @@ -265,12 +265,12 @@ type Response struct { // // 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,omitempty"` // 联系方式 - License *License `json:"license,omitempty"` // 开源协议 - Version string `json:"version" required:"true"` // 必选. API 文档的版本信息（注意：这个版本和开放 API 规范版本没有任何关系）。 + 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,omitempty" required:"true"` // 必选. API 文档的版本信息（注意：这个版本和开放 API 规范版本没有任何关系）。 } // Contact 联系人信息 @@ -290,8 +290,8 @@ type Contact struct { // // Date : 16:09 2024/4/19 type License struct { - Name string `json:"name"` // 开源协议名 - Url string `json:"url"` // 开源协议地址 + Name string `json:"name,omitempty"` // 开源协议名 + Url string `json:"url,omitempty"` // 开源协议地址 } // ServerItem server 对象结构 @@ -300,9 +300,9 @@ type License struct { // // 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中. 变量名 -> 变量配置 + 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 ... @@ -311,9 +311,9 @@ type ServerItem struct { // // Date : 14:22 2024/7/19 type ServerItemVariable struct { - Default string `json:"default"` // 变量默认值 - Description string `json:"description"` // 变量描述 - Enum []string `json:"enum"` // 变量枚举值 + Default string `json:"default,omitempty"` // 变量默认值 + Description string `json:"description,omitempty"` // 变量描述 + Enum []string `json:"enum,omitempty"` // 变量枚举值 } // TagItem 每一个标签数据结构 @@ -322,6 +322,6 @@ type ServerItemVariable struct { // // Date : 12:18 2024/7/19 type TagItem struct { - Name string `json:"name"` // 标签名称 - Description string `json:"description"` // 标签描述 + Name string `json:"name,omitempty"` // 标签名称 + Description string `json:"description,omitempty"` // 标签描述 } diff --git a/parser_test.go b/parser_test.go index 7e3f360..805d9fc 100644 --- a/parser_test.go +++ b/parser_test.go @@ -32,7 +32,7 @@ func Test_parser_Openapi3(t *testing.T) { var bArr *B g := NewOpenapiDoc(nil, nil) g.AddApiFromInAndOut(&define.UriBaseConfig{ - Uri: "/a/b/c/d", + Uri: "/ent/user/detail", Method: http.MethodPost, ContentType: []string{"application/x-www-form-urlencoded"}, OutputContentType: []string{"application/yml", "application/json", "application/xml"},