Tag 对象

Adds metadata to a single tag that is used by the Operation 对象. It is not mandatory to have a Tag Object per tag defined in the Operation Object instances.

固定字段

字段名	类型	描述
name	string	必选. The name of the tag.
description	string	A short description for the tag. CommonMark syntax可以被用来呈现富文本格式.
externalDocs	External Documentation 对象	Additional external documentation for this tag.

这个对象可能会被规范扩展扩展。

Tag 对象示例

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

name: pet
description: Pets operations

Examples 对象

In an example, a JSON Reference MAY be used, with the explicit restriction that examples having a JSON format with object named $ref are not allowed. Therefore, that example, structurally, can be either a string primitive or an object, similar to additionalProperties.

In all cases, the payload is expected to be compatible with the type schema for the associated value. Tooling implementations MAY choose to validate compatibility automatically, and reject the example value(s) if they are incompatible.

# in a model
schemas:
  properties:
    name:
      type: string
      example:
        $ref: http://foo.bar#/examples/name-example

  # in a request body, note the plural `examples`
  requestBody:
    content:
      'application/json':
        schema:
          $ref: '#/components/schemas/Address'
        examples:
          foo:
            value: { 'foo': 'bar' }
          bar:
            value: { 'bar': 'baz' }
      'application/xml':
        examples:
          xml:
            externalValue: 'http://foo.bar/examples/address-example.xml'
      'text/plain':
        examples:
          text:
            externalValue: 'http://foo.bar/examples/address-example.txt'

  # in a parameter
  parameters:
    - name: 'zipCode'
      in: 'query'
      schema:
        type: 'string'
        format: 'zip-code'
        example:
          $ref: 'http://foo.bar#/examples/zip-example'

  # in a response, note the singular `example`:
  responses:
    '200':
      description: your car appointment has been booked
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SuccessResponse'
          example:
            $ref: http://foo.bar#/examples/address-example.json