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。
+	RequestBody  *RequestBody           `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 外部文档配置
@@ -167,7 +155,64 @@ type XML struct {
 	Wrapped   bool   `json:"wrapped"`   // 只可被用于数组定义。表示数组是否被包裹（比如, <books><book/><book/></books>）或未被包裹（<book/><book/>）。默认值是 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 信息