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 ...