优化openapi文档数据结构定义
This commit is contained in:
parent
99a84d8083
commit
f885f61f62
@ -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"` // 标签描述
|
||||
}
|
||||
|
||||
@ -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"},
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user