swagger和openAPI: 组件部分

作者: Arvin Chen 分类: Swagger 来源: Break易站(www.breakyizhan.com)

组件部分

通常,多个API操作具有一些通用参数或返回相同的响应结构。为避免代码重复,您可以将常用定义放置在全局  components部分中并使用它们进行引用$ref

在下面的示例中,用户对象的重复定义被替换为单个组件以及对该组件的引用。

之前:

paths:
  /users/{userId}:
    get:
      summary: Get a user by ID
      parameters:
        ...
      responses:
        '200':
          description: A single user.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  name:
                    type: string
  /users:
    get:
      summary: Get all users
      responses:
        '200':
          description: A list of users.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                    name:
                      type: string

后:

paths:
  /users/{userId}:
    get:
      summary: Get a user by ID
      parameters:
        ...
      responses:
        '200':
          description: A single user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
  /users:
    get:
      summary: Get all users
      responses:
        '200':
          description: A list of users.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string

组件结构

components充当各种可重用定义的容器 - 模式(数据模型),参数,响应,示例等。这些定义components对API没有直接影响,除非你明确地从外部引用它们components。也就是说,components不是适用于所有操作的参数和响应; 他们只是其他地方参考的信息片段。

在下面components,定义按类型分组 - schemas,parameters依此类推。以下示例列出了可用的子部分。所有小节都是可选的。

components:
  # Reusable schemas (data models)
  schemas:
    ...

  # Reusable path, query, header and cookie parameters
  parameters:
    ...

  # Security scheme definitions (see Authentication)
  securitySchemes:
    ...

  # Reusable request bodies
  requestBodies:
    ...

  # Reusable responses, such as 401 Unauthorized or 400 Bad Request
  responses:
    ...

  # Reusable response headers
  headers:
    ...

  # Reusable examples
  examples:
    ...

  # Reusable links
  links:
    ...

  # Reusable callbacks
  callbacks:
    ...

每个小节包含一个或多个命名组件(定义):

components:
  schemas:
    User:
      type: object
      ...
    Pet:
      type: object
      ...

组件名称只能由以下字符组成:

A..Z a..z 0..9 . _ -

有效名称的例子:

User
New_User
org.example.User
401-Unauthorized

组件名称用于通过$refAPI规范的其他部分引用组件:

$ref: '#/components/<type>/<name>'

例如:

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

一个例外是securitySchemes通过名称直接引用的定义  (请参阅认证)。

组件示例

下面是components包含可重用数据模式,参数和响应的示例。其他组件类型(链接,示例和其他)的定义类似。

components:
  #-------------------------------
  # Reusable schemas (data models)
  #-------------------------------
  schemas:
    User:             # Can be referenced as '#/components/schemas/User'
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string

    Error:            # Can be referenced as '#/components/schemas/Error'
      type: object
      properties:
        code:
          type: integer
        message:
          type: string

  #-------------------------------
  # Reusable operation parameters
  #-------------------------------
  parameters:
    offsetParam:      # Can be referenced via '#/components/parameters/offsetParam'
      name: offset
      in: query
      description: Number of items to skip before returning the results.
      required: false
      schema:
        type: integer
        format: int32
        minimum: 0
        default: 0

    limitParam:       # Can be referenced as '#/components/parameters/limitParam'
      name: limit
      in: query
      description: Maximum number of items to return.
      required: false
      schema:
        type: integer
        format: int32
        minimum: 1
        maximum: 100
        default: 20

  #-------------------------------
  # Reusable responses
  #-------------------------------
  responses:
    404NotFound:       # Can be referenced as '#/components/responses/404NotFound'
      description: The specified resource was not found.

    ImageResponse:     # Can be referenced as '#/components/responses/ImageResponse'
      description: An image.
      content:
        image/*:
          schema:
            type: string
            format: binary

    GenericError:      # Can be referenced as '#/components/responses/GenericError'
      description: An error occurred.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

外部定义的组件

components可以内联指定单个定义(如前面的示例中)或使用$ref对外部定义的引用:

components:
  schemas:
    Pet:
      $ref: '../models/pet.yaml'
      # Can now use use '#/components/schemas/Pet' instead
    User:
      $ref: 'https://api.example.com/v2/openapi.yaml#/components/schemas/User'
      # Can now use '#/components/schemas/User' instead

  responses:
    GenericError:
      $ref: '../template-api.yaml#/components/responses/GenericError'
      # Can now use '#/components/responses/GenericError' instead

这样,您可以为外部定义定义本地“别名”,而不必在所有引用中重复使用外部文件路径。如果引用文件的位置发生更改,则只需将其更改为一个位置(in components)而不是所有引用。

与OpenAPI 2.0的差异

OpenAPI的2.0对可重用组件单独的章节- ,,definitions 和。在OpenAPI 3.0中,它们都被移入了内部。此外,被重命名为和 已更名为(注不同的拼法:VS )。parametersresponsessecurityDefinitionscomponentsdefinitionsschemassecurityDefinitionssecuritySchemesschemAssecuritySchemEs

参考资料会相应更改以反映新结构:

OpenAPI 2.0                    OpenAPI 3.0
'#/definitions/User'         → '#/components/schemes/User'
'#/parameters/offsetParam'   → '#/components/parameters/offsetParam'
'#/responses/ErrorResponse'  → '#/components/responses/ErrorResponse'
  •   本文标题:swagger和openAPI: 组件部分 - Break易站
    转载请保留页面地址:https://www.breakyizhan.com/swagger/2991.html

    发表笔记

    电子邮件地址不会被公开。 必填项已用*标注

    更多阅读