OpenAPI 规范 v3.0.2

此对象可以使用规范扩展进行扩展。

此对象可以使用规范扩展进行扩展。

{
  "title": "Sample Pet Store App",
  "description": "This is a sample server for a pet store.",
  "termsOfService": "http://example.com/terms/",
  "contact": {
    "name": "API Support",
    "url": "http://www.example.com/support",
    "email": "[email protected]"
  },
  "license": {
    "name": "Apache 2.0",
    "url": "https://www.apache.org/licenses/LICENSE-2.0.html"
  },
  "version": "1.0.1"
}

title: Sample Pet Store App
description: This is a sample server for a pet store.
termsOfService: http://example.com/terms/
contact:
  name: API Support
  url: http://www.example.com/support
  email: [email protected]
license:
  name: Apache 2.0
  url: https://www.apache.org/licenses/LICENSE-2.0.html
version: 1.0.1

此对象可以使用规范扩展进行扩展。

{
  "name": "API Support",
  "url": "http://www.example.com/support",
  "email": "[email protected]"
}

name: API Support
url: http://www.example.com/support
email: [email protected]

此对象可以使用规范扩展进行扩展。

{
  "name": "Apache 2.0",
  "url": "https://www.apache.org/licenses/LICENSE-2.0.html"
}

name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html

此对象可以使用规范扩展进行扩展。

单个服务器将被描述为

{
  "url": "https://development.gigantic-server.com/v1",
  "description": "Development server"
}

url: https://development.gigantic-server.com/v1
description: Development server

以下展示了如何描述多个服务器，例如，在 OpenAPI 对象的 servers 中。

{
  "servers": [
    {
      "url": "https://development.gigantic-server.com/v1",
      "description": "Development server"
    },
    {
      "url": "https://staging.gigantic-server.com/v1",
      "description": "Staging server"
    },
    {
      "url": "https://api.gigantic-server.com/v1",
      "description": "Production server"
    }
  ]
}

servers:
- url: https://development.gigantic-server.com/v1
  description: Development server
- url: https://staging.gigantic-server.com/v1
  description: Staging server
- url: https://api.gigantic-server.com/v1
  description: Production server

以下展示了如何在服务器配置中使用变量。

{
  "servers": [
    {
      "url": "https://{username}.gigantic-server.com:{port}/{basePath}",
      "description": "The production API server",
      "variables": {
        "username": {
          "default": "demo",
          "description": "this value is assigned by the service provider, in this example `gigantic-server.com`"
        },
        "port": {
          "enum": [
            "8443",
            "443"
          ],
          "default": "8443"
        },
        "basePath": {
          "default": "v2"
        }
      }
    }
  ]
}

servers:
- url: https://{username}.gigantic-server.com:{port}/{basePath}
  description: The production API server
  variables:
    username:
      # note! no enum here means it is an open value
      default: demo
      description: this value is assigned by the service provider, in this example `gigantic-server.com`
    port:
      enum:
        - '8443'
        - '443'
      default: '8443'
    basePath:
      # open meaning there is the opportunity to use special base paths as assigned by the provider, default is `v2`
      default: v2

此对象可以使用规范扩展进行扩展。

此对象可以使用规范扩展进行扩展。

上面声明的所有固定字段都是对象，这些对象必须使用与正则表达式匹配的键：^[a-zA-Z0-9\.\-_]+$。

字段名称示例

User
User_1
User_Name
user-name
my.org.User

"components": {
  "schemas": {
    "GeneralError": {
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "format": "int32"
        },
        "message": {
          "type": "string"
        }
      }
    },
    "Category": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer",
          "format": "int64"
        },
        "name": {
          "type": "string"
        }
      }
    },
    "Tag": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer",
          "format": "int64"
        },
        "name": {
          "type": "string"
        }
      }
    }
  },
  "parameters": {
    "skipParam": {
      "name": "skip",
      "in": "query",
      "description": "number of items to skip",
      "required": true,
      "schema": {
        "type": "integer",
        "format": "int32"
      }
    },
    "limitParam": {
      "name": "limit",
      "in": "query",
      "description": "max records to return",
      "required": true,
      "schema" : {
        "type": "integer",
        "format": "int32"
      }
    }
  },
  "responses": {
    "NotFound": {
      "description": "Entity not found."
    },
    "IllegalInput": {
      "description": "Illegal input for operation."
    },
    "GeneralError": {
      "description": "General Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/GeneralError"
          }
        }
      }
    }
  },
  "securitySchemes": {
    "api_key": {
      "type": "apiKey",
      "name": "api_key",
      "in": "header"
    },
    "petstore_auth": {
      "type": "oauth2",
      "flows": {
        "implicit": {
          "authorizationUrl": "http://example.org/api/oauth/dialog",
          "scopes": {
            "write:pets": "modify pets in your account",
            "read:pets": "read your pets"
          }
        }
      }
    }
  }
}

components:
  schemas:
    GeneralError:
      type: object
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
    Category:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
    Tag:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
  parameters:
    skipParam:
      name: skip
      in: query
      description: number of items to skip
      required: true
      schema:
        type: integer
        format: int32
    limitParam:
      name: limit
      in: query
      description: max records to return
      required: true
      schema:
        type: integer
        format: int32
  responses:
    NotFound:
      description: Entity not found.
    IllegalInput:
      description: Illegal input for operation.
    GeneralError:
      description: General Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GeneralError'
  securitySchemes:
    api_key:
      type: apiKey
      name: api_key
      in: header
    petstore_auth:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: http://example.org/api/oauth/dialog
          scopes:
            write:pets: modify pets in your account
            read:pets: read your pets

此对象可以使用规范扩展进行扩展。

假设以下路径，如果使用具体定义/pets/mine，将首先匹配。

  /pets/{petId}
  /pets/mine

以下路径被认为是相同的且无效的。

  /pets/{petId}
  /pets/{name}

以下可能会导致模糊解析。

  /{entity}/me
  /books/{id}

{
  "/pets": {
    "get": {
      "description": "Returns all pets from the system that the user has access to",
      "responses": {
        "200": {         
          "description": "A list of pets.",
          "content": {
            "application/json": {
              "schema": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/pet"
                }
              }
            }
          }
        }
      }
    }
  }
}

/pets:
  get:
    description: Returns all pets from the system that the user has access to
    responses:
      '200':
        description: A list of pets.
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/pet'

此对象可以使用规范扩展进行扩展。

{
  "get": {
    "description": "Returns pets based on ID",
    "summary": "Find pets by ID",
    "operationId": "getPetsById",
    "responses": {
      "200": {
        "description": "pet response",
        "content": {
          "*/*": {
            "schema": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/Pet"
              }
            }
          }
        }
      },
      "default": {
        "description": "error payload",
        "content": {
          "text/html": {
            "schema": {
              "$ref": "#/components/schemas/ErrorModel"
            }
          }
        }
      }
    }
  },
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "description": "ID of pet to use",
      "required": true,
      "schema": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "style": "simple"
    }
  ]
}

get:
  description: Returns pets based on ID
  summary: Find pets by ID
  operationId: getPetsById
  responses:
    '200':
      description: pet response
      content:
        '*/*' :
          schema:
            type: array
            items:
              $ref: '#/components/schemas/Pet'
    default:
      description: error payload
      content:
        'text/html':
          schema:
            $ref: '#/components/schemas/ErrorModel'
parameters:
- name: id
  in: path
  description: ID of pet to use
  required: true
  schema:
    type: array
    style: simple
    items:
      type: string 

此对象可以使用规范扩展进行扩展。

{
  "tags": [
    "pet"
  ],
  "summary": "Updates a pet in the store with form data",
  "operationId": "updatePetWithForm",
  "parameters": [
    {
      "name": "petId",
      "in": "path",
      "description": "ID of pet that needs to be updated",
      "required": true,
      "schema": {
        "type": "string"
      }
    }
  ],
  "requestBody": {
    "content": {
      "application/x-www-form-urlencoded": {
        "schema": {
          "type": "object",
           "properties": {
              "name": {
                "description": "Updated name of the pet",
                "type": "string"
              },
              "status": {
                "description": "Updated status of the pet",
                "type": "string"
             }
           },
        "required": ["status"]
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Pet updated.",
      "content": {
        "application/json": {},
        "application/xml": {}
      }
    },
    "405": {
      "description": "Method Not Allowed",
      "content": {
        "application/json": {},
        "application/xml": {}
      }
    }
  },
  "security": [
    {
      "petstore_auth": [
        "write:pets",
        "read:pets"
      ]
    }
  ]
}

tags:
- pet
summary: Updates a pet in the store with form data
operationId: updatePetWithForm
parameters:
- name: petId
  in: path
  description: ID of pet that needs to be updated
  required: true
  schema:
    type: string
requestBody:
  content:
    'application/x-www-form-urlencoded':
      schema:
       properties:
          name:
            description: Updated name of the pet
            type: string
          status:
            description: Updated status of the pet
            type: string
       required:
         - status
responses:
  '200':
    description: Pet updated.
    content:
      'application/json': {}
      'application/xml': {}
  '405':
    description: Method Not Allowed
    content:
      'application/json': {}
      'application/xml': {}
security:
- petstore_auth:
  - write:pets
  - read:pets

此对象可以使用规范扩展进行扩展。

{
  "description": "Find more info here",
  "url": "https://example.com"
}

description: Find more info here
url: https://example.com

in字段指定了四个可能的参数位置。

• path - 与 路径模板 结合使用，其中参数值实际上是操作 URL 的一部分。这并不包括 API 的主机或基本路径。例如，在 /items/{itemId} 中，路径参数是 itemId。
• query - 附加到 URL 的参数。例如，在 /items?id=### 中，查询参数是 id。
• header - 预期作为请求一部分的自定义标头。请注意，[RFC7230] 第 22 页 指出标头名称不区分大小写。
• cookie - 用于将特定的 cookie 值传递给 API。

参数序列化的规则以两种方式之一指定。对于更简单的场景，schema 和 style 可以描述参数的结构和语法。

对于更复杂的场景，content 属性可以定义参数的媒体类型和模式。参数必须包含 schema 属性或 content 属性，但不能同时包含两者。当 example 或 examples 与 schema 对象一起提供时，示例必须遵循参数规定的序列化策略。

为了支持序列化简单参数的常用方法，定义了一组 style 值。

假设名为 color 的参数具有以下值之一

   string -> "blue"
   array -> ["blue","black","brown"]
   object -> { "R": 100, "G": 200, "B": 150 }

下表显示了每个值的渲染差异示例。

此对象可以使用规范扩展进行扩展。

具有 64 位整数数组的标头参数

{
  "name": "token",
  "in": "header",
  "description": "token to be passed as a header",
  "required": true,
  "schema": {
    "type": "array",
    "items": {
      "type": "integer",
      "format": "int64"
    }
  },
  "style": "simple"
}

name: token
in: header
description: token to be passed as a header
required: true
schema:
  type: array
  items:
    type: integer
    format: int64
style: simple

字符串值的路径参数

{
  "name": "username",
  "in": "path",
  "description": "username to fetch",
  "required": true,
  "schema": {
    "type": "string"
  }
}

name: username
in: path
description: username to fetch
required: true
schema:
  type: string

字符串值的可选查询参数，通过重复查询参数允许多个值

{
  "name": "id",
  "in": "query",
  "description": "ID of the object to fetch",
  "required": false,
  "schema": {
    "type": "array",
    "items": {
      "type": "string"
    }
  },
  "style": "form",
  "explode": true
}

name: id
in: query
description: ID of the object to fetch
required: false
schema:
  type: array
  items:
    type: string
style: form
explode: true

自由格式查询参数，允许特定类型的未定义参数

{
  "in": "query",
  "name": "freeForm",
  "schema": {
    "type": "object",
    "additionalProperties": {
      "type": "integer"
    },
  },
  "style": "form"
}

in: query
name: freeForm
schema:
  type: object
  additionalProperties:
    type: integer
style: form

使用 content 定义序列化的复杂参数

{
  "in": "query",
  "name": "coordinates",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "required": [
          "lat",
          "long"
        ],
        "properties": {
          "lat": {
            "type": "number"
          },
          "long": {
            "type": "number"
          }
        }
      }
    }
  }
}

in: query
name: coordinates
content:
  application/json:
    schema:
      type: object
      required:
        - lat
        - long
      properties:
        lat:
          type: number
        long:
          type: number

此对象可以使用规范扩展进行扩展。

具有引用模型定义的请求正文。

{
  "description": "user to add to the system",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/User"
      },
      "examples": {
          "user" : {
            "summary": "User Example",
            "externalValue": "http://foo.bar/examples/user-example.json"
          }
        }
    },
    "application/xml": {
      "schema": {
        "$ref": "#/components/schemas/User"
      },
      "examples": {
          "user" : {
            "summary": "User example in XML",
            "externalValue": "http://foo.bar/examples/user-example.xml"
          }
        }
    },
    "text/plain": {
      "examples": {
        "user" : {
            "summary": "User example in Plain text",
            "externalValue": "http://foo.bar/examples/user-example.txt"
        }
      }
    },
    "*/*": {
      "examples": {
        "user" : {
            "summary": "User example in other format",
            "externalValue": "http://foo.bar/examples/user-example.whatever"
        }
      }
    }
  }
}

description: user to add to the system
content:
  'application/json':
    schema:
      $ref: '#/components/schemas/User'
    examples:
      user:
        summary: User Example
        externalValue: 'http://foo.bar/examples/user-example.json'
  'application/xml':
    schema:
      $ref: '#/components/schemas/User'
    examples:
      user:
        summary: User Example in XML
        externalValue: 'http://foo.bar/examples/user-example.xml'
  'text/plain':
    examples:
      user:
        summary: User example in text plain format
        externalValue: 'http://foo.bar/examples/user-example.txt'
  '*/*':
    examples:
      user:
        summary: User example in other format
        externalValue: 'http://foo.bar/examples/user-example.whatever'

作为字符串值数组的正文参数

{
  "description": "user to add to the system",
  "content": {
    "text/plain": {
      "schema": {
        "type": "array",
        "items": {
          "type": "string"
        }
      }
    }
  }
}

description: user to add to the system
required: true
content:
  text/plain:
    schema:
      type: array
      items:
        type: string

此对象可以使用规范扩展进行扩展。

{
  "application/json": {
    "schema": {
         "$ref": "#/components/schemas/Pet"
    },
    "examples": {
      "cat" : {
        "summary": "An example of a cat",
        "value":
          {
            "name": "Fluffy",
            "petType": "Cat",
            "color": "White",
            "gender": "male",
            "breed": "Persian"
          }
      },
      "dog": {
        "summary": "An example of a dog with a cat's name",
        "value" :  {
          "name": "Puma",
          "petType": "Dog",
          "color": "Black",
          "gender": "Female",
          "breed": "Mixed"
        },
      "frog": {
          "$ref": "#/components/examples/frog-example"
        }
      }
    }
  }
}

application/json:
  schema:
    $ref: "#/components/schemas/Pet"
  examples:
    cat:
      summary: An example of a cat
      value:
        name: Fluffy
        petType: Cat
        color: White
        gender: male
        breed: Persian
    dog:
      summary: An example of a dog with a cat's name
      value:
        name: Puma
        petType: Dog
        color: Black
        gender: Female
        breed: Mixed
    frog:
      $ref: "#/components/examples/frog-example"

与 2.0 规范相比，OpenAPI 中的 file 输入/输出内容使用与任何其他模式类型相同的语义进行描述。具体来说

# content transferred with base64 encoding
schema:
  type: string
  format: base64

# content transferred in binary (octet-stream):
schema:
  type: string
  format: binary

这些示例适用于文件上传的输入有效负载或响应有效负载。

用于在 POST 操作中提交文件的 requestBody 可能如下例所示

requestBody:
  content:
    application/octet-stream:
      # any media type is accepted, functionally equivalent to `*/*`
      schema:
        # a binary file of any type
        type: string
        format: binary

此外，可以指定特定的媒体类型MAY。

# multiple, specific media types may be specified:
requestBody:
  content:
      # a binary file of type png or jpeg
    'image/jpeg':
      schema:
        type: string
        format: binary
    'image/png':
      schema:
        type: string
        format: binary       

要上传多个文件，必须使用multipart媒体类型。

requestBody:
  content:
    multipart/form-data:
      schema:
        properties:
          # The property name 'file' will be used for all files.
          file:
            type: array
            items:
              type: string
              format: binary

要使用[RFC1866]通过表单 URL 编码提交内容，可以使用以下定义

requestBody:
  content:
    application/x-www-form-urlencoded:
      schema:
        type: object
        properties:
          id:
            type: string
            format: uuid
          address:
            # complex types are stringified to support RFC 1866
            type: object
            properties: {}

在此示例中，当传递到服务器时，requestBody中的内容必须根据[RFC1866]进行字符串化。此外，address字段的复杂对象也将被字符串化。

当在application/x-www-form-urlencoded内容类型中传递复杂对象时，此类属性的默认序列化策略在Encoding Object的style属性中描述为form。

将multipart/form-data用作将请求主体传输到操作时的Content-Type很常见。与 2.0 相比，当使用multipart内容时，需要一个schema来定义操作的输入参数。这支持复杂结构以及支持多种文件上传的机制。

当传递multipart类型时，可以使用边界来分隔正在传输的内容部分——因此，为multipart定义了以下默认Content-Type

• 如果属性是基本类型，或基本类型的数组，则默认 Content-Type 为text/plain
• 如果属性是复杂类型，或复杂类型的数组，则默认 Content-Type 为application/json
• 如果属性是type: string且format: binary或format: base64（也称为文件对象），则默认 Content-Type 为application/octet-stream

示例

requestBody:
  content:
    multipart/form-data:
      schema:
        type: object
        properties:
          id:
            type: string
            format: uuid
          address:
            # default Content-Type for objects is `application/json`
            type: object
            properties: {}
          profileImage:
            # default Content-Type for string/binary is `application/octet-stream`
            type: string
            format: binary
          children:
            # default Content-Type for arrays is based on the `inner` type (text/plain here)
            type: array
            items:
              type: string
          addresses:
            # default Content-Type for arrays is based on the `inner` type (object shown, so `application/json` in this example)
            type: array
            items:
              type: '#/components/schemas/Address'

引入encoding属性以控制multipart请求主体部分的序列化。此属性仅适用于multipart和application/x-www-form-urlencoded请求主体。

此对象可以使用规范扩展进行扩展。

requestBody:
  content:
    multipart/mixed:
      schema:
        type: object
        properties:
          id:
            # default is text/plain
            type: string
            format: uuid
          address:
            # default is application/json
            type: object
            properties: {}
          historyMetadata:
            # need to declare XML format!
            description: metadata in XML format
            type: object
            properties: {}
          profileImage:
            # default is application/octet-stream, need to declare an image type only!
            type: string
            format: binary
      encoding:
        historyMetadata:
          # require XML Content-Type in utf-8 encoding
          contentType: application/xml; charset=utf-8
        profileImage:
          # only accept png/jpeg
          contentType: image/png, image/jpeg
          headers:
            X-Rate-Limit-Limit:
              description: The number of allowed requests in the current period
              schema:
                type: integer

此对象可以使用规范扩展进行扩展。

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

{
  "200": {
    "description": "a pet to be returned",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/Pet"
        }
      }
    }
  },
  "default": {
    "description": "Unexpected error",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ErrorModel"
        }
      }
    }
  }
}

'200':
  description: a pet to be returned
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/Pet'
default:
  description: Unexpected error
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/ErrorModel'

此对象可以使用规范扩展进行扩展。

复杂类型数组的响应

{
  "description": "A complex object array response",
  "content": {
    "application/json": {
      "schema": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/VeryComplexType"
        }
      }
    }
  }
}

description: A complex object array response
content:
  application/json:
    schema:
      type: array
      items:
        $ref: '#/components/schemas/VeryComplexType'

带有字符串类型的响应

{
  "description": "A simple string response",
  "content": {
    "text/plain": {
      "schema": {
        "type": "string"
      }
    }
  }

}

description: A simple string response
content:
  text/plain:
    schema:
      type: string

带有标头的纯文本响应

{
  "description": "A simple string response",
  "content": {
    "text/plain": {
      "schema": {
        "type": "string"
      }
    }
  },
  "headers": {
    "X-Rate-Limit-Limit": {
      "description": "The number of allowed requests in the current period",
      "schema": {
        "type": "integer"
      }
    },
    "X-Rate-Limit-Remaining": {
      "description": "The number of remaining requests in the current period",
      "schema": {
        "type": "integer"
      }
    },
    "X-Rate-Limit-Reset": {
      "description": "The number of seconds left in the current period",
      "schema": {
        "type": "integer"
      }
    }
  }
}

description: A simple string response
content:
  text/plain:
    schema:
      type: string
    example: 'whoa!'
headers:
  X-Rate-Limit-Limit:
    description: The number of allowed requests in the current period
    schema:
      type: integer
  X-Rate-Limit-Remaining:
    description: The number of remaining requests in the current period
    schema:
      type: integer
  X-Rate-Limit-Reset:
    description: The number of seconds left in the current period
    schema:
      type: integer

没有返回值的响应

{
  "description": "object created"
}

description: object created

此对象可以使用规范扩展进行扩展。

标识Path Item Object的键是一个运行时表达式，可以在运行时 HTTP 请求/响应的上下文中计算，以标识将用于回调请求的 URL。一个简单的示例可能是$request.body#/url。但是，使用运行时表达式可以访问完整的 HTTP 消息。这包括访问 JSON 指针[RFC6901]可以引用的主体任何部分。

例如，给定以下 HTTP 请求

POST /subscribe/myevent?queryUrl=http://clientdomain.com/stillrunning HTTP/1.1
Host: example.org
Content-Type: application/json
Content-Length: 187

{
  "failedUrl" : "http://clientdomain.com/failed",
  "successUrls" : [
    "http://clientdomain.com/fast",
    "http://clientdomain.com/medium",
    "http://clientdomain.com/slow"
  ]
}

201 Created
Location: http://example.org/subscription/1

以下示例显示了各种表达式的计算方式，假设回调操作具有名为eventType的路径参数和名为queryUrl的查询参数。

以下示例显示了对请求主体中id和email属性指定的 URL 的回调。

myWebhook:
  'http://notificationServer.com?transactionId={$request.body#/id}&email={$request.body#/email}':
    post:
      requestBody:
        description: Callback payload
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/SomePayload'
      responses:
        '200':
          description: webhook successfully processed and no retries will be performed

此对象可以使用规范扩展进行扩展。

在所有情况下，示例值都应与其关联值的类型模式兼容。工具实现可以选择自动验证兼容性，并在不兼容时拒绝示例值。

在模型中

schemas:
  properties:
    name:
      type: string
      examples:
        name:
          $ref: http://example.org/petapi-examples/openapi.json#/components/examples/name-example

在请求主体中

requestBody:
  content:
    'application/json':
      schema:
        $ref: '#/components/schemas/Address'
      examples:
        foo:
          summary: A foo example
          value: {"foo": "bar"}
        bar:
          summary: A bar example
          value: {"bar": "baz"}
    'application/xml':
      examples:
        xmlExample:
          summary: This is an example in XML
          externalValue: 'http://example.org/examples/address-example.xml'
    'text/plain':
      examples:
        textExample:
          summary: This is a text example
          externalValue: 'http://foo.bar/examples/address-example.txt'

在参数中

parameters:
  - name: 'zipCode'
    in: 'query'
    schema:
      type: 'string'
      format: 'zip-code'
      examples:
        zip-example:
          $ref: '#/components/examples/zip-example'

在响应中

responses:
  '200':
    description: your car appointment has been booked
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/SuccessResponse'
        examples:
          confirmation-success:
            $ref: '#/components/examples/confirmation-success'

此对象可以使用规范扩展进行扩展。

链接操作必须使用operationRef或operationId进行标识。在operationId的情况下，它必须在 OAS 文档的范围内是唯一的并且已解析。由于可能发生名称冲突，因此对于具有外部引用的规范，建议使用operationRef语法。

从请求操作计算链接，其中$request.path.id用于将请求参数传递给链接操作。

paths:
  /users/{id}:
    parameters:
    - name: id
      in: path
      required: true
      description: the user identifier, as userId
      schema:
        type: string
    get:
      responses:
        '200':
          description: the user being returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  uuid: # the unique user id
                    type: string
                    format: uuid
          links:
            address:
              # the target link operationId
              operationId: getUserAddress
              parameters:
                # get the `id` field from the request path parameter named `id`
                userId: $request.path.id
  # the path item of the linked operation
  /users/{userid}/address:
    parameters:
    - name: userid
      in: path
      required: true
      description: the user identifier, as userId
      schema:
        type: string
    # linked operation
    get:
      operationId: getUserAddress
      responses:
        '200':
          description: the user's address

当运行时表达式计算失败时，不会将任何参数值传递给目标操作。

响应主体中的值可用于驱动链接操作。

links:
  address:
    operationId: getUserAddressByUUID
    parameters:
      # get the `uuid` field from the `uuid` field in the response body
      userUuid: $response.body#/uuid

客户端自行决定是否遵循所有链接。仅凭关系的存在并不能保证权限或成功调用该链接的能力。

由于对operationId的引用可能不可行（operationId是可选值），因此也可以通过相对operationRef进行引用

links:
  UserRepositories:
    # returns array of '#/components/schemas/repository'
    operationRef: '#/paths/~12.0~1repositories~1{username}/get'
    parameters:
      username: $response.body#/username

或绝对operationRef

links:
  UserRepositories:
    # returns array of '#/components/schemas/repository'
    operationRef: 'https://na2.gigantic-server.com/#/paths/~12.0~1repositories~1{username}/get'
    parameters:
      username: $response.body#/username

请注意，在使用operationRef时，当使用 JSON 引用时，转义的正斜杠是必要的。

运行时表达式允许根据仅在实际 API 调用中 HTTP 消息内可用的信息定义值。此机制由链接对象和回调对象使用。

运行时表达式由以下[ABNF]语法定义

      expression = ( "$url" | "$method" | "$statusCode" | "$request." source | "$response." source )
      source = ( header-reference | query-reference | path-reference | body-reference ) 
      header-reference = "header." token
      query-reference = "query." name 
      path-reference = "path." name
      body-reference = "body" ["#" fragment]
      fragment = a JSON Pointer [RFC 6901](https://tools.ietf.org/html/rfc6901) 
      name = *( char )
      char = as per RFC [7159](https://tools.ietf.org/html/rfc7159#section-7)
      token = as per RFC [7230](https://tools.ietf.org/html/rfc7230#section-3.2.6)

name标识符区分大小写，而token不区分大小写。

下表提供了运行时表达式的示例及其在值中使用的示例

运行时表达式保留引用的值的类型。表达式可以通过用{}花括号括起来嵌入到字符串值中。

一个简单的类型为integer的标头

{
  "description": "The number of allowed requests in the current period",
  "schema": {
    "type": "integer"
  }
}

description: The number of allowed requests in the current period
schema:
  type: integer

此对象可以使用规范扩展进行扩展。

{
	"name": "pet",
	"description": "Pets operations"
}

name: pet
description: Pets operations

此对象不能使用其他属性进行扩展，并且添加的任何属性都应被忽略。

{
	"$ref": "#/components/schemas/Pet"
}

$ref: '#/components/schemas/Pet'

{
  "$ref": "Pet.json"
}

$ref: Pet.yaml

{
  "$ref": "definitions.json#/Pet"
}

$ref: definitions.yaml#/Pet

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

• title
• multipleOf
• maximum
• exclusiveMaximum
• minimum
• exclusiveMinimum
• maxLength
• minLength
• pattern（此字符串应是有效的正则表达式，根据ECMA 262 正则表达式方言）
• maxItems
• minItems
• uniqueItems
• maxProperties
• minProperties
• required
• enum

以下属性取自 JSON Schema 定义，但其定义已调整为 OpenAPI 规范。

• type - 值必须是字符串。不支持通过数组使用多个类型。
• allOf - 内联或引用的模式必须是Schema 对象，而不是标准的 JSON Schema。
• oneOf - 内联或引用的模式必须是Schema 对象，而不是标准的 JSON Schema。
• anyOf - 内联或引用的模式必须是Schema 对象，而不是标准的 JSON Schema。
• not - 内联或引用的模式必须是Schema 对象，而不是标准的 JSON Schema。
• items - 值必须是对象，而不是数组。内联或引用的模式必须是Schema 对象，而不是标准的 JSON Schema。如果type为array，则必须存在items。
• properties - 属性定义必须是Schema 对象，而不是标准的 JSON Schema（内联或引用）。
• additionalProperties - 值可以是布尔值或对象。内联或引用的模式必须是Schema 对象，而不是标准的 JSON Schema。与 JSON Schema 一致，additionalProperties默认为true。
• description - [CommonMark]语法可以用于富文本表示。
• format - 请参阅数据类型格式以获取更多详细信息。虽然依赖于 JSON Schema 定义的格式，但 OAS 提供了一些其他预定义格式。
• default - 默认值表示如果未提供输入的值，则输入的使用者将假定为模式的值。与 JSON Schema 不同，该值必须符合在同一级别定义的 Schema 对象的定义类型。例如，如果type为string，则default可以为"foo"，但不能为1。

或者，在可以使用 Schema 对象的任何时候，都可以使用引用对象来代替它。这允许引用定义而不是内联定义它们。

此处未提及的 JSON Schema 规范定义的其他属性严格不支持。

除了 JSON Schema 子集字段之外，以下字段可以用于进一步的模式文档

此对象可以使用规范扩展进行扩展。