相关文章推荐
痴情的苹果  ·  Update request.auth ...·  10 月前    · 
开朗的烈酒  ·  对当前我国存在的暴力恐怖活动的研究与思考_中 ...·  1 年前    · 
睿智的登山鞋  ·  【大庆油田累计生产原油突破25亿吨】-国家发 ...·  1 年前    · 
任性的马克杯  ·  用Python ...·  1 年前    · 
鬼畜的帽子  ·  中越边境10大陆地边境口岸各自的贸易特色和贸 ...·  2 年前    · 
Code  ›  OpenAPI 规范 v2.0 - OpenAPI 倡议
html语言 xml解析 xml格式 swagger
https://spec.openapis.org.cn/oas/v2.0.html
潇洒的电梯
2 月前

什么是 OpenAPI 规范？

OpenAPI 规范 (OAS) 为 HTTP API 定义了一个标准的、与编程语言无关的接口描述，使人类和计算机都能够在无需访问源代码、其他文档或检查网络流量的情况下发现和理解服务的 能力。当通过 OpenAPI 正确定义时，使用者可以使用最少的实现逻辑来理解和交互远程服务。类似于接口描述对较低级别编程所做的工作，OpenAPI 规范消除了调用服务的猜测。

本文档的状态

此规范的真相来源是上面引用的 HTML 文件，名为“此版本”。

1. OpenAPI 规范

2. (原 Swagger RESTful API 文档规范)

2.1 版本 2.0

本文档中的关键词“ 必须 ”、“ 禁止 ”、“ 必需 ”、“ 应 ”、“ 不应 ”、“ 应该 ”、“ 不应该 ”、“ 推荐 ”、“ 可能 ”和“ 可选 ”的解释方式如 [ RFC2119 ] 中所述。

Swagger 规范根据 Apache 许可证 2.0 版 授权。

3. 简介

Swagger™ 是一个用于描述和记录 RESTful API 的项目。

Swagger 规范定义了一组描述此类 API 所需的文件。然后，Swagger-UI 项目可以使用这些文件来显示 API，而 Swagger-Codegen 可以使用这些文件生成各种语言的客户端。其他实用程序（如测试工具）也可以利用生成的文件。

4. 修订历史

路径模板指的是使用花括号 ({}) 来标记 URL 路径的一部分，以便使用路径参数替换。

5.2 MIME 类型

MIME 类型定义分散在多个资源中。MIME 类型定义应符合 [ RFC6838 ]。

一些可能的 MIME 类型定义示例 

  text/plain; charset=utf-8
  application/json
  application/vnd.github+json
  application/vnd.github.v3+json
  application/vnd.github.v3.raw+json
  application/vnd.github.v3.text+json
  application/vnd.github.v3.html+json
  application/vnd.github.v3.full+json
  application/vnd.github.v3.diff
  application/vnd.github.v3.patch

5.3 HTTP 状态码

HTTP 状态码用于指示执行操作的状态。可用状态码由 [ RFC7231 ] 第 6 节 和 IANA 状态码注册表 描述。

6. 规范

6.1 格式

根据 Swagger 规范描述 RESTful API 的文件表示为 JSON 对象，并符合 JSON 标准。 YAML 作为 JSON 的超集，也可以用来表示 Swagger 规范文件。

例如，如果说某个字段具有数组值，则将使用 JSON 数组表示法

"field" : [...]

虽然 API 使用 JSON 进行描述，但它本身并不强制 API 使用 JSON 作为输入/输出。

规范中的所有字段名称都 区分大小写 。

模式公开了两种类型的字段。固定字段，具有声明的名称；模式化字段，为字段名称声明正则表达式模式。模式化字段可以有多个出现，只要每个字段都有唯一的名称。

6.2 文件结构

API 的 Swagger 表示由单个文件组成。但是，可以根据用户的意愿将定义的一部分拆分为单独的文件。这适用于规范中的 $ref 字段，这一点来自 JSON Schema 定义。

按照惯例，Swagger 规范文件名为 swagger.json 。

6.3 数据类型

Swagger 规范中的原始数据类型基于 JSON-Schema 草案 4 支持的类型。模型使用 Schema 对象 进行描述，该对象是 JSON Schema 草案 4 的一个子集。

参数对象 和 响应对象 使用额外的原始数据类型 "file" 来设置参数类型或响应为文件。

原始数据类型有一个可选的修饰符属性 format 。Swagger 使用一些已知的格式来更精确地定义正在使用的类型。但是， format 属性是一个开放的 string 值属性，可以具有任何值以支持文档需求。即使未在此规范中定义，也可以使用诸如 "email" 、 "uuid" 等格式。未附带 format 属性的类型遵循其在 JSON Schema 中的定义（除了上面定义的 file 类型）。Swagger 规范定义的格式为

提供 API 的主机（名称或 IP）。这 必须 仅为主机，不包括方案或子路径。它 可以 包含端口。如果未包含 host ，则使用提供文档的主机（包括端口）。 host 不支持 路径模板 。 basePath 提供 API 的基本路径，相对于 host 。如果未包含它，则 API 将直接在 host 下提供。值 必须 以斜杠 ( / ) 开头。 basePath 不支持 路径模板 。 schemes [ string ] API 的传输协议。值 必须 来自以下列表： "http" 、 "https" 、 "ws" 、 "wss" 。如果未包含 schemes ，则使用访问 Swagger 定义本身所用的默认方案。 consumes [ string ] API 可以使用的 MIME 类型列表。这对于所有 API 都是全局的，但可以在特定的 API 调用中被覆盖。值 必须 如 MIME 类型 中所述。 produces [ string ] API 可以生成的 MIME 类型列表。这对于所有 API 都是全局的，但可以在特定的 API 调用中被覆盖。值 必须 如 MIME 类型 中所述。 paths 必需。 API 可用的路径和操作。 definitions 一个用于保存操作产生和使用的的数据类型的对象。 parameters 参数定义对象 一个用于保存可以在操作之间使用的参数的对象。此属性 不 定义所有操作的全局参数。 responses 响应定义对象 一个用于保存可以在操作之间使用的响应的对象。此属性 不 定义所有操作的全局响应。 securityDefinitions 安全定义对象 可以在规范中使用的安全方案定义。 security [ 安全需求对象 ] 声明 API 整体应用哪些安全方案。值列表描述了可使用的替代安全方案（即，安全需求之间存在逻辑 OR）。各个操作可以覆盖此定义。 [ 标签对象 ] 规范使用的标签列表，以及其他元数据。标签的顺序可用于反映解析工具对其的顺序。并非 操作对象 使用的所有标签都必须声明。未声明的标签可以随机组织或基于工具的逻辑组织。列表中的每个标签名称 必须 唯一。 externalDocs 外部文档对象 其他外部文档。
6.4.1.2 模式化对象
"title" : "Swagger Sample App" , "description" : "This is a sample server Petstore server." , "termsOfService" : "https://swagger.org.cn/terms/" , "contact" : { "name" : "API Support" , "url" : "http://www.swagger.io/support" , "email" : "support@swagger.io" "license" : { "name" : "Apache 2.0" , "url" : "https://apache.ac.cn/licenses/LICENSE-2.0.html" "version" : "1.0.1" 
title: Swagger Sample App
description: This is a sample server Petstore server.
termsOfService: https://swagger.org.cn/terms/
contact:
  name: API Support
  url: http://www.swagger.io/support
  email: support@swagger.io
license:
  name: Apache 2.0
  url: https://apache.ac.cn/licenses/LICENSE-2.0.html
version: 1.0.1

6.4.3 Contact 对象

公开 API 的联系信息。

6.4.3.1 固定字段
"name" : "API Support" , "url" : "http://www.swagger.io/support" , "email" : "support@swagger.io" 
name: API Support
url: http://www.swagger.io/support
email: support@swagger.io

6.4.4 License 对象

公开 API 的许可证信息。

6.4.4.1 固定字段
"/pets" : { "get" : { "description" : "Returns all pets from the system that the user has access to" , "produces" : [ "application/json" "responses" : { "200" : { "description" : "A list of pets." , "schema" : { "type" : "array" , "items" : { "$ref" : "#/definitions/pet" 
/pets:
    description: Returns all pets from the system that the user has access to
    produces:
    - application/json
    responses:
      '200':
        description: A list of pets.
        schema:
          type: array
          items:
            $ref: '#/definitions/pet'

6.4.6 Path Item 对象

描述单个路径上可用的操作。由于 ACL 约束 ，路径项可能为空。路径本身仍然会显示给文档查看器，但他们将不知道哪些操作和参数可用。

6.4.6.1 固定字段
"description" : "Returns pets based on ID" , "summary" : "Find pets by ID" , "operationId" : "getPetsById" , "produces" : [ "application/json" , "text/html" "responses" : { "200" : { "description" : "pet response" , "schema" : { "type" : "array" , "items" : { "$ref" : "#/definitions/Pet" "default" : { "description" : "error payload" , "schema" : { "$ref" : "#/definitions/ErrorModel" "parameters" : [ "name" : "id" , "in" : "path" , "description" : "ID of pet to use" , "required" : true , "type" : "array" , "items" : { "type" : "string" "collectionFormat" : "csv" description: Returns pets based on ID summary: Find pets by ID operationId: getPetsById produces: - application/json - text/html responses: '200': description: pet response schema: type: array items: $ref: '#/definitions/Pet' default: description: error payload schema: $ref: '#/definitions/ErrorModel' parameters: - name: id in: path description: ID of pet to use required: true type: array items: type: string collectionFormat: csv

6.4.7 Operation 对象

描述路径上的单个 API 操作。

6.4.7.1 固定字段
operationId 用于识别操作的唯一字符串。此 ID 必须 在 API 中描述的所有操作之间唯一。工具和库 可以 使用 operationId 来唯一地识别操作，因此，建议遵循常见的编程命名约定。 consumes [ string ] 操作可以接收的 MIME 类型列表。这会覆盖 Swagger 对象中 consumes 的定义。空值 可以 用于清除全局定义。值 必须 按照 MIME 类型 中的描述进行定义。 produces [ string ] 操作可以产生的 MIME 类型列表。这会覆盖 Swagger 对象中 produces 的定义。空值 可以 用于清除全局定义。值 必须 按照 MIME 类型 中的描述进行定义。 parameters [ 参数对象 | 引用对象 ] 适用于此操作的参数列表。如果参数已在 路径项目 中定义，则新定义将覆盖它，但永远不会将其移除。列表 绝不能 包含重复的参数。唯一参数由 名称 和 位置 的组合定义。列表可以使用 引用对象 来链接到 Swagger 对象的参数 中定义的参数。最多只能有一个“body”参数。 responses 必填。 执行此操作后返回的可能响应列表。 schemes [ string ] 操作的传输协议。值 必须 来自以下列表： "http" 、 "https" 、 "ws" 、 "wss" 。该值会覆盖 Swagger 对象 schemes 的定义。 deprecated 声明此操作已弃用。应避免使用声明的操作。默认值为 false 。 security [ 安全需求对象 ] 声明对此操作应用哪些安全方案。值的列表描述了可使用的替代安全方案（即，安全需求之间存在逻辑或）。此定义会覆盖任何已声明的顶级 security 。要删除顶级安全声明，可以使用空数组。
6.4.7.2 模式化对象
"summary" : "Updates a pet in the store with form data" , "description" : "" , "operationId" : "updatePetWithForm" , "consumes" : [ "application/x-www-form-urlencoded" "produces" : [ "application/json" , "application/xml" "parameters" : [ "name" : "petId" , "in" : "path" , "description" : "ID of pet that needs to be updated" , "required" : true , "type" : "string" "name" : "name" , "in" : "formData" , "description" : "Updated name of the pet" , "required" : false , "type" : "string" "name" : "status" , "in" : "formData" , "description" : "Updated status of the pet" , "required" : false , "type" : "string" "responses" : { "200" : { "description" : "Pet updated." "405" : { "description" : "Invalid input" "security" : [ "petstore_auth" : [ "write:pets" , "read:pets" 
tags:
- pet
summary: Updates a pet in the store with form data
description: ""
operationId: updatePetWithForm
consumes:
- application/x-www-form-urlencoded
produces:
- application/json
- application/xml
parameters:
- name: petId
  in: path
  description: ID of pet that needs




    
 to be updated
  required: true
  type: string
- name: name
  in: formData
  description: Updated name of the pet
  required: false
  type: string
- name: status
  in: formData
  description: Updated status of the pet
  required: false
  type: string
responses:
  '200':
    description: Pet updated.
  '405':
    description: Invalid input
security:
- petstore_auth:
  - write:pets
  - read:pets

6.4.8 External Documentation 对象

允许引用外部资源以获取扩展文档。

6.4.8.1 固定字段

有五种可能的参数类型。

  • 路径 - 与 路径模板 一起使用，其中参数值实际上是操作 URL 的一部分。这并不包括 API 的主机或基本路径。例如，在 /items/{itemId} 中，路径参数为 itemId 。
  • 查询 - 附加到 URL 的参数。例如，在 /items?id=### 中，查询参数为 id 。
  • 标头 - 预期作为请求一部分的自定义标头。
  • 主体 - 附加到 HTTP 请求的有效负载。由于只能有一个有效负载，因此只能有一个主体参数。主体参数的名称对参数本身没有影响，仅用于文档目的。由于表单参数也位于有效负载中，因此对于相同操作，主体参数和表单参数不能同时存在。
  • 表单 - 用于描述 HTTP 请求的有效负载，当使用 application/x-www-form-urlencoded 、 multipart/form-data 或两者都用作请求的内容类型时（在 Swagger 的定义中，操作的 consumes 属性）。这是唯一可用于发送文件的参数类型，因此支持 file 类型。由于表单参数发送在有效负载中，因此它们不能与相同操作的主体参数一起声明。表单参数基于所使用的内容类型具有不同的格式（有关更多详细信息，请参阅 [ HTML401 ] 第 17.13.4 节

    • 6.4.11 Responses 对象

    操作预期响应的容器。该容器将 HTTP 响应代码映射到预期响应。文档不需要覆盖所有可能的 HTTP 响应代码，因为它们可能事先未知。但是，文档需要覆盖成功操作的响应和任何已知的错误。

    default 可以用作所有未单独由规范涵盖的 HTTP 代码的默认响应对象。

    Responses Object 必须 包含至少一个响应代码，并且它 应该 是成功操作调用的响应。

    6.4.11.1 固定字段
    { HTTP 状态代码 } Response Object | Reference Object 任何 HTTP 状态代码 都可以用作属性名称（每个 HTTP 状态代码一个属性）。描述该 HTTP 状态代码的预期响应。 Reference Object 可用于链接到在 Swagger Object’s responses 部分定义的响应。 允许 Swagger Schema 的扩展。字段名称 必须 以 x- 开头，例如 x-internal-id 。值可以是 null 、基本类型、数组或对象。有关详细信息，请参阅 供应商扩展 。
    6.4.11.3 Responses 对象示例

    成功操作的 200 响应以及其他响应的默认响应（暗示错误）。

    "200" : { "description" : "a pet to be returned" , "schema" : { "$ref" : "#/definitions/Pet" "default" : { "description" : "Unexpected error" , "schema" : { "$ref" : "#/definitions/ErrorModel" 
    '200':
  description: a pet to be returned
  schema:
    $ref: '#/definitions/Pet'
default:
  description: Unexpected error
  schema:
    $ref: '#/definitions/ErrorModel'

    6.4.12 Response 对象

    描述 API 操作的单个响应。

    6.4.12.1 固定字段
    schema 响应结构的定义。它可以是基本类型、数组或对象。如果此字段不存在，则表示没有内容作为响应的一部分返回。作为 Schema Object 的扩展，其根 type 值也可能是 "file" 。这 应该 与相关的 produces MIME 类型一起使用。 headers Headers Object 与响应一起发送的标头列表。 examples Example Object 响应消息的示例。
    6.4.12.2 模式化对象
    "headers" : { "X-Rate-Limit-Limit" : { "description" : "The number of allowed requests in the current period" , "type" : "integer" "X-Rate-Limit-Remaining" : { "description" : "The number of remaining requests in the current period" , "type" : "integer" "X-Rate-Limit-Reset" : { "description" : "The number of seconds left in the current period" , "type" : "integer" 
    description: A simple string response
schema:
  type: string
headers:
  X-Rate-Limit-Limit:




    

    description: The number of allowed requests in the current period
    type: integer
  X-Rate-Limit-Remaining:
    description: The number of remaining requests in the current period
    type: integer
  X-Rate-Limit-Reset:
    description: The number of seconds left in the current period
    type: integer

    没有返回值的响应。
    
  "description": "object created"

    description: object created

    6.4.13 Headers 对象

    列出可以作为响应的一部分发送的标头。

    6.4.13.1 模式化字段
    "X-Rate-Limit-Limit" : { "description" : "The number of allowed requests in the current period" , "type" : "integer" "X-Rate-Limit-Remaining" : { "description" : "The number of remaining requests in the current period" , "type" : "integer" "X-Rate-Limit-Reset" : { "description" : "The number of seconds left in the current period" , "type" : "integer" 
    X-Rate-Limit-Limit:
  description: The number of allowed requests in the current period
  type: integer
X-Rate-Limit-Remaining:
  description: The number of remaining requests in the current period
  type: integer
X-Rate-Limit-Reset:
  description: The number of seconds left in the current period
  type: integer

    6.4.14 Example 对象

    允许共享操作响应的示例。

    6.4.14.1 模式化字段
    collectionFormat 如果使用类型数组，则确定数组的格式。可能的值为
    • csv - 逗号分隔值 foo,bar 。
    • ssv - 空格分隔值 foo bar 。
    • tsv - 制表符分隔值 foo\tbar 。
    • pipes - 管道分隔值 foo|bar 。
    默认值为 csv 。 default 声明服务器在未提供任何值时将使用的标头的值。（注意：“default”对于必需标头没有意义。）请参见     https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-6.2 。与 JSON Schema 不同，此值 必须 符合为标头定义的 type 。 maximum 请参阅 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2 。 exclusiveMaximum 请参阅 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2 。 minimum 请参阅 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3 。 exclusiveMinimum 请参阅 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3 。 maxLength 请参阅 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.1 。 minLength 请参阅 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.2 。 pattern 请参阅 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.3 。 maxItems 请参阅 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.2 。 minItems 请参阅 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.3 。 uniqueItems https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.4 . 请参阅 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.5.1 。 multipleOf 请参阅 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.1 。
    6.4.15.1 模式化对象
    "description" : "The number of allowed requests in the current period" , "type" : "integer" 
    description: The number of allowed requests in the current period
type: integer

    6.4.16 Tag 对象

    允许向由 Operation Object 使用的单个标签添加元数据。每个在那里使用的标签都不一定需要一个 Tag Object。

    6.4.16.1 固定字段

    6.4.17 Reference 对象

    一个简单的对象，用于引用规范中的其他定义。它可以用来引用在顶级定义以供重复使用的参数和响应。

    Reference Object 是一个 JSON 参考 ，它使用 JSON 指针 [ RFC6901 ] 作为其值。对于此规范，仅支持 规范反引用 。

    6.4.17.1 固定字段

    6.4.18 Schema 对象

    Schema Object 允许定义输入和输出数据类型。这些类型可以是对象，也可以是基本类型和数组。此对象基于 JSON Schema 规范草案 4 ，并使用其预定义的子集。在此子集之上，此规范提供了扩展以允许更完整的文档。

    有关属性的更多信息，请参阅 JSON Schema Core 和 JSON Schema Validation 。除非另有说明，否则属性定义遵循此处引用的 JSON Schema 规范。

    以下属性直接取自 JSON Schema 定义，并遵循相同的规范

  • $ref - 作为 JSON 参考
  • format（有关更多详细信息，请参见 数据类型格式 ）
  • title
  • description（ GFM 语法 可用于富文本表示）
  • default（与 JSON Schema 不同，该值 必须 符合 Schema Object 定义的类型）
  • multipleOf
  • maximum
  • exclusiveMaximum
  • minimum
  • exclusiveMinimum
  • maxLength
  • minLength
  • pattern
  • maxItems
  • minItems
  • uniqueItems
  • maxProperties
  • minProperties
  • required

    • 以下属性取自 JSON Schema 定义，但其定义已调整为 Swagger 规范。其定义与 JSON Schema 中的定义相同，只是在原始定义引用 JSON Schema 定义时，使用 Schema Object 定义。

  • items
  • allOf
  • properties
  • additionalProperties

    • 除了 JSON Schema 子集字段之外，以下字段可用于进一步的架构文档。

    6.4.18.1 固定字段
    discriminator 添加对多态性的支持。鉴别器是用于区分继承此架构的其他架构的架构属性名称。使用的属性名称 必须 在此架构中定义，并且它 必须 在 required 属性列表中。使用时，该值 必须 是此架构或任何继承它的架构的名称。 readOnly 仅与 Schema "properties" 定义相关。将属性声明为“只读”。这意味着它 可以 作为响应的一部分发送，但 绝不能 作为请求的一部分发送。标记为 readOnly 为 true 的属性 不应该在定义的架构的 required 列表中。默认值为 false 。 XML Object 这 可以 仅用于属性架构。它对根架构没有影响。添加其他元数据以描述此属性的 XML 表示格式。 externalDocs 外部文档对象 此架构的其他外部文档。 example 一个自由格式的属性，用于包含此架构实例的示例。
    6.4.18.2 模式化对象
    6.4.18.2.1 组合和继承（多态）

    Swagger 允许使用 JSON Schema 的 allOf 属性组合和扩展模型定义，从而有效地提供模型组合。 allOf 接收一个对象定义数组，这些定义 独立 验证，但共同构成一个对象。

    虽然组合提供了模型的可扩展性，但它并不意味着模型之间存在层次结构。为了支持多态性，Swagger 添加了对 discriminator 字段的支持。使用时， discriminator 将是用于确定使用哪个架构定义来验证模型结构的属性的名称。因此， discriminator 字段 必须 是必需字段。所选属性的值必须是 definitions 属性下给模型的友好名称。因此，没有给定 ID 的内联架构定义 不能 用于多态性。

    6.4.18.2.2 XML 建模

    当将 JSON 定义转换为 XML 时， xml 属性允许额外的定义。 XML 对象 包含有关可用选项的其他信息。

    6.4.18.3 Schema 对象示例
    6.4.18.3.1 基本示例

    与 Swagger 的早期版本不同，模式定义也可用于描述基本类型和数组。

    "type" : "string" , "format" : "email" 
    type: string
format: email
    6.4.18.3.2 简单模型
    "type" : "object" , "required" : [ "name" "properties" : { "name" : { "type" : "string" "address" : { "$ref" : "#/definitions/Address" "age" : { "type" : "integer" , "format" : "int32" , "minimum" : 0 
    type: object
required:
- name
properties:
  name:
    type: string
  address:
    $ref: '#/definitions/Address'
    type: integer
    format: int32
    minimum: 0
    6.4.18.3.3 具有映射/字典属性的模型

    对于简单的字符串到字符串映射

    "type" : "object" , "additionalProperties" : { "type" : "string" 
    type: object
additionalProperties:
  type: string

    对于字符串到模型的映射
    
  "type": "object",
  "additionalProperties": {
    "$ref": "#/definitions/ComplexModel"

    type: object
additionalProperties:
  $ref: '#/definitions/ComplexModel'
    6.4.18.3.4 带有示例的模型
    "type" : "object" , "properties" : { "id" : { "type" : "integer" , "format" : "int64" "name" : { "type" : "string" "required" : [ "name" "example" : { "name" : "Puma" , "id" : 1 
    type: object
properties:
    type: integer
    format: int64
  name:
    type: string
required:
- name
example:
  name: Puma
  id: 1
    6.4.18.3.5 具有组合的模型
    "definitions" : { "ErrorModel" : { "type" : "object" , "required" : [ "message" , "code" "properties" : { "message" : { "type" : "string" "code" : { "type" : "integer" , "minimum" : 100 , "maximum" : 600 "ExtendedErrorModel" : { "allOf" : [ "$ref" : "#/definitions/ErrorModel" "type" : "object" , "required" : [ "rootCause" "properties" : { "rootCause" : { "type" : "string" 
    definitions:
  ErrorModel:
    type: object
    required:
    - message
    - code
    properties:
      message:
        type: string
      code:
        type: integer
        minimum: 100
        maximum: 600
  ExtendedErrorModel:
    allOf:
    - $ref: '#/definitions/ErrorModel'
    - type: object
      required:
      - rootCause
      properties:
        rootCause:
          type: string
    6.4.18.3.6 支持多态的模型
    "definitions" : { "Pet" : { "type" : "object" , "discriminator" : "petType" , "properties" : { "name" : { "type" : "string" "petType" : { "type" : "string" "required" : [ "name" , "petType" "Cat" : { "description" : "A representation of a cat" , "allOf" : [ "$ref" : "#/definitions/Pet" "type" : "object" , "properties" : { "huntingSkill" : { "type" : "string" , "description" : "The measured skill for hunting" , "default" : "lazy" , "enum" : [ "clueless" , "lazy" , "adventurous" , "aggressive" "required" : [ "huntingSkill" "Dog" : { "description" : "A representation of a dog" , "allOf" : [ "$ref" : "#/definitions/Pet" "type" : "object" , "properties" : { "packSize" : { "type" : "integer" , "format" : "int32" , "description" : "the size of the pack the dog is from" , "default" : 0 , "minimum" : 0 "required" : [ "packSize" 
    definitions:
    type: object
    discriminator: petType
    properties:
      name:
        type: string
      petType:
        type: string
    required:
    - name
    - petType
    description: A representation of a cat
    allOf:
    - $ref: '#/definitions/Pet'
    - type: object
      properties:
        huntingSkill:
          type: string
          description: The measured skill for hunting
          default: lazy
          enum:
          - clueless
          - lazy
          - adventurous
          - aggressive
      required:
      - huntingSkill
    description: A representation of a dog
    allOf:
    - $ref: '#/definitions/Pet'
    - type: object
      properties:
        packSize:
          type: integer
          format: int32
          description: the size of the pack the dog is from
          default: 0
          minimum: 0
      required:
      - packSize

    6.4.19 XML 对象

    一个元数据对象，允许更精细的 XML 模型定义。

    使用数组时，不会推断 XML 元素名称（对于单数/复数形式），并且应使用 name 属性添加该信息。请参阅示例以了解预期行为。

    6.4.19.1 固定字段
    替换用于描述的模式属性的元素/属性的名称。在 Items 对象 ( items ) 中定义时，它将影响列表中各个 XML 元素的名称。当与 type 为 array 一起定义（在 items 之外）时，它将影响包装元素，并且仅当 wrapped 为 true 时。如果 wrapped 为 false ，则将忽略它。 namespace 命名空间定义的 URL。值 SHOULD 采用 URL 的形式。 prefix 用于 name 的前缀。 attribute 声明属性定义是否转换为属性而不是元素。默认值为 false 。 wrapped MAY 仅用于数组定义。表示数组是否被包装（例如， <books><book/><book/></books> ）或未包装（ <book/><book/> ）。默认值为 false 。仅当与 type 为 array 一起定义（在 items 之外）时，此定义才生效。
    6.4.19.2 模式化对象 
    <Person id="123">
    <sample:name xmlns:sample="https://swagger.org.cn/schema/sample">example</sample:name>
</Person>
    6.4.19.3.4 XML 数组

    更改元素名称

    "animals" : { "type" : "array" , "items" : { "type" : "string" , "xml" : { "name" : "animal" 
    animals:
  type: array
  items:
    type: string
      name: animal

    <animal>value</animal>
<animal>value</animal>

    外部 name 属性对 XML 没有影响
    
  "animals": {
    "type": "array",
    "items": {
      "type": "string",
      "xml": {
        "name": "animal"
    "xml": {
      "name": "aliens"

    animals:
  type: array
  items:
    type: string
      name: animal
    name: aliens

    <animal>value</animal>
<animal>value</animal>

    即使数组被包装，如果未明确定义名称，则内部和外部都将使用相同的名称
    
  "animals": {
    "type": "array",
    "items": {
      "type": "string"
    "xml": {
      "wrapped": true

    animals:
  type: array
  items:
    type: string
    wrapped: true

    <animals>
  <animals>value</animals>
  <animals>value</animals>
</animals>

    为了克服上述示例，可以使用以下定义
    
  "animals": {
    "type": "array",
    "items": {
      "type": "string",
      "xml": {
        "name": "animal"
    "xml": {
      "wrapped": true

    animals:
  type: array
  items:
    type: string
      name: animal
    wrapped: true

    <animals>
  <animal>value</animal>
  <animal>value</animal>
</animals>

    影响内部和外部名称
    
  "animals": {
    "type": "array"




    
,
    "items": {
      "type": "string",
      "xml": {
        "name": "animal"
    "xml": {
      "name": "aliens",
      "wrapped": true

    animals:
  type: array
  items:
    type: string
      name: animal
    name: aliens
    wrapped: true

    <aliens>
  <animal>value</animal>
  <animal>value</animal>
</aliens>

    如果我们更改外部元素但未更改内部元素
    
  "animals": {
    "type": "array",
    "items": {
      "type": "string"
    "xml": {
      "name": "aliens",
      "wrapped": true

    animals:
  type: array
  items:
    type: string
    name: aliens
    wrapped: true

    <aliens>
  <aliens>value</aliens>
  <aliens>value</aliens>
</aliens>

    6.4.20 Definitions 对象

    一个对象，用于保存操作可以消费和产生的数据类型。这些数据类型可以是基本类型、数组或模型。

    6.4.20.1 模式化字段
    description: Entity not found. IllegalInput: description: Illegal input for operation. GeneralError: description: General Error schema: $ref: '#/definitions/GeneralError'

    6.4.23 Security Definitions 对象

    可用于规范中提供的安全方案的声明。这不会在操作上强制执行安全方案，而仅用于提供每个方案的相关详细信息。

    6.4.23.1 模式化字段
    "petstore_auth" : { "type" : "oauth2" , "authorizationUrl" : "https://swagger.org.cn/api/oauth/dialog" , "flow" : "implicit" , "scopes" : { "write:pets" : "modify pets in your account" , "read:pets" : "read your pets" 
    api_key:
  type: apiKey
  name: api_key
  in: header
petstore_auth:
  type: oauth2
  authorizationUrl: https://swagger.org.cn/api/oauth/dialog
  flow: implicit
  scopes:
    write:pets: modify pets in your account
    read:pets: read your pets

    6.4.24 Security Scheme 对象

    允许定义可由操作使用的安全方案。支持的方案包括基本身份验证、API 密钥（作为标头或查询参数）以及 OAuth2 的常用流程（隐式、密码、应用程序和访问代码）。

    6.4.24.1 固定字段
    oauth2 必需。 OAuth2 安全方案使用的流程。有效值为 "implicit" 、 "password" 、 "application" 或 "accessCode" 。 authorizationUrl oauth2 ( "implicit" , "accessCode" ) 必需。 要用于此流程的授权 URL。这 SHOULD 采用 URL 的形式。 tokenUrl oauth2 ( "password" , "application" , "accessCode" ) 必需。 要用于此流程的令牌 URL。这 SHOULD 采用 URL 的形式。 scopes 作用域对象 oauth2 必需。 OAuth2 安全方案的可用作用域。
    6.4.24.2 模式化字段
    "type" : "oauth2" , "authorizationUrl" : "https://swagger.org.cn/api/oauth/dialog" , "flow" : "implicit" , "scopes" : { "write:pets" : "modify pets in your account" , "read:pets" : "read your pets" 
    type: oauth2
authorizationUrl: https://swagger.org.cn/api/oauth/dialog
flow: implicit
scopes:
  write:pets: modify pets in your account
  read:pets: read your pets

    6.4.25 Scopes 对象

    列出 OAuth2 安全方案的可用作用域。

    6.4.25.1 模式化字段

    6.4.26 Security Requirement 对象

    列出执行此操作所需的安全性方案。该对象可以在其中声明多个安全性方案，这些方案都是必需的（即，方案之间存在逻辑 AND）。

    每个属性使用的名称 MUST 对应于 安全定义 中声明的安全方案。

    6.4.26.1 模式化字段

    虽然 Swagger 规范试图适应大多数用例，但可以在某些点添加其他数据以扩展规范。

    扩展属性始终以 "x-" 为前缀，并且可以具有任何有效的 JSON 格式值。

    可用的工具可能支持也可能不支持扩展，但也可以扩展这些工具以添加请求的支持（如果工具是内部的或开源的）。

    6.6 安全过滤

    Swagger 规范中的一些对象可能会被声明并保持为空，或者完全删除，即使它们本质上是 API 文档的核心。

    这样做的原因是为了允许对文档本身进行额外的访问控制层。虽然本身不是规范的一部分，但某些库可能会选择根据某种形式的身份验证/授权来允许访问文档的某些部分。

    以下是两个示例

  • 路径对象 可能为空。这可能违反直觉，但这可能会告诉查看者他们到达了正确的位置，但无法访问任何文档。他们仍然可以访问 信息对象 ，其中可能包含有关身份验证的其他信息。
  • 路径项对象 可能为空。在这种情况下，查看者将知道路径存在，但将无法查看其任何操作或参数。这与从 路径对象 中隐藏路径本身不同，因此用户将不知道其存在。这允许文档提供者更精细地控制查看者可以看到的内容。

    • A. 参考文献

    A.1 规范性引用

    [HTML401]
    HTML 4.01 规范 。Dave Raggett；Arnaud Le Hors；Ian Jacobs。W3C。2018 年 3 月 27 日。W3C 建议。URL： https://www.w3.org/TR/html401/
    [IANA-HTTP-STATUS-CODES]
    超文本传输协议 (HTTP) 状态代码注册表 。IANA。URL： https://www.iana.org/assignments/http-status-codes/
    [JSON-Reference]
    JSON 引用 。Paul Bryan；Kris Zyp。互联网工程任务组 (IETF)。2012 年 9 月 16 日。互联网草案。URL： https://datatracker.ietf.org/doc/html/draft-pbryan-zyp-json-ref-03
    [JSON-Schema-04]
    JSON 模式：核心定义和术语。草案 4 。Kris Zyp；Francis Galiegue；Gary Court。互联网工程任务组 (IETF)。2013 年 1 月 31 日。互联网草案。URL： https://datatracker.ietf.org/doc/html/draft-zyp-json-schema-04
    [JSON-Schema-Validation-04]
    JSON 模式：交互式和非交互式验证。草案 4 。Kris Zyp；Francis Galiegue；Gary Court。互联网工程任务组 (IETF)。2013 年 2 月 1 日。互联网草案。URL： https://datatracker.ietf.org/doc/html/draft-fge-json-schema-validation-00
    [RFC2119]
    用于 RFC 中指示需求级别的关键词 。S. Bradner。IETF。1997 年 3 月。最佳当前实践。URL： https://www.rfc-editor.org/rfc/rfc2119
    [RFC3339]
    互联网上的日期和时间：时间戳 。G. Klyne；C. Newman。IETF。2002 年 7 月。建议标准。URL： https://www.rfc-editor.org/rfc/rfc3339
    [RFC6838]
    媒体类型规范和注册程序 。N. Freed；J. Klensin；T. Hansen。IETF。2013 年 1 月。最佳当前实践。URL： https://www.rfc-editor.org/rfc/rfc6838
    [RFC6901]
    JavaScript 对象表示法 (JSON) 指针 。P. Bryan，编辑；K. Zyp；M. Nottingham，编辑。IETF。2013 年 4 月。建议标准。URL： https://www.rfc-editor.org/rfc/rfc6901
    [RFC7159]
    JavaScript 对象表示法 (JSON) 数据交换格式 。T. Bray，编辑。IETF。2014 年 3 月。建议标准。URL： https://www.rfc-editor.org/rfc/rfc7159
    [RFC7231]
    超文本传输协议 (HTTP/1.1)：语义和内容 。R. Fielding，编辑；J. Reschke，编辑。IETF。2014 年 6 月。建议标准。URL： https://httpwg.org/specs/rfc7231.html
    [YAML]
    YAML Ain’t Markup Language (YAML™) 版本 1.2 。Oren Ben-Kiki；Clark Evans；Ingy döt Net。2009 年 10 月 1 日。URL： http://yaml.org/spec/1.2/spec.html
  • 未在本文件中引用。
    •  
    推荐文章
    痴情的苹果  ·  Update request.auth instead of request.user · Issue #76 · vitalik/django-ninja · GitHub
    10 月前
    开朗的烈酒  ·  对当前我国存在的暴力恐怖活动的研究与思考_中国犯罪学学会
    1 年前
    睿智的登山鞋  ·  【大庆油田累计生产原油突破25亿吨】-国家发展和改革委员会
    1 年前
    任性的马克杯  ·  用Python 3对文件进行异或加密/解密-腾讯云开发者社区-腾讯云
    1 年前
    鬼畜的帽子  ·  中越边境10大陆地边境口岸各自的贸易特色和贸易市场你知道多少？_东兴
    2 年前
    今天看啥   ·   Py中国   ·   codingpro   ·   小百科   ·   link之家   ·   卧龙AI搜索
    删除内容请联系邮箱 2879853325@qq.com
    Code - 代码工具平台
    © 2024 ~ 沪ICP备11025650号