• Tags ,
  •         
  • 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'

     
    转载请保留页面地址:https://www.breakyizhan.com/swagger/2991.html