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 信息