Components 对象

包含开放 API 规范固定的各种可重用组件。当没有被其他对象引用时，在这里定义定义的组件不会产生任何效果。

固定字段

字段名	类型	描述
schemas	Map[string, Schema 对象 | Reference 对象]	定义可重用的 Schema 对象 的对象。
responses	Map[string, Response 对象 | Reference 对象]	定义可重用的 Response 对象 的对象。
parameters	Map[string, Parameter 对象 | Reference 对象]	定义可重用的 Parameter 对象 的对象。
examples	Map[string, Example 对象 | Reference 对象]	定义可重用的 Example 对象 的对象。
requestBodies	Map[string, Request Body 对象 | Reference 对象]	定义可重用的 Request Body 对象 的对象。
headers	Map[string, Header 对象 | Reference 对象]	定义可重用的 Header 对象 的对象。
securitySchemes	Map[string, Security Scheme 对象 | Reference 对象]	定义可重用的 Security Scheme 对象 的对象。
links	Map[string, Link 对象 | Reference 对象]	定义可重用的 Link 对象
的对象。
callbacks	Map[string, Callback 对象 | Reference 对象]	定义可重用的 Callback 对象 的对象。

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

上面定义的所有固定字段的值都是对象，对象包含的 key 的命名必须满足正则表达式： ^[a-zA-Z0-9\.\-_]+$。

字段名示例:

User
User_1
User_Name
user-name
my.org.User

Components 对象示例

{
  "components": {
    "schemas": {
      "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:
    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