如何在 Swagger 中重用模式

Question

在我的 Swagger 文档中，我必须多次使用相同的模式。目前，它被重复放置。

我改进的一件事是制作通用参数（通过在组件内声明它）。但是找不到任何东西来避免parameters 和schemas 之间的这种重复模式。

有什么办法，我可以使用一次声明此模式并在需要的地方重新使用它？

我的 Swagger 看起来像：

openapi: 3.0.3
info:
  title: My System
  description: Self contained system
  version: 1.0.0
servers:
  - url: /a/{aId}/
    description: Contains the partition
security:
  - bearerAuth: []
paths:
  
  "/x/{xId}/y/{yId}/z/{zId}":
    get:
      x-horizon-permission: "geo.floorplan.read"
      tags:
        - myTag
      operationId: getValue
      description: Get Value
      parameters:
        - name: xId
          in: path
          required: true
          schema:
            type: string
            pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
        - name: yId
          in: path
          required: true
          schema:
            type: string
            pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
        - name: zId
          in: path
          required: true
          schema:
            type: string
            pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
      responses:
        "200":
          description: OK
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/Response'
    patch:
      tags:
        - myTag
      operationId: Update
      description: Update Data
      parameters:
        - name: xId
          in: path
          required: true
          schema:
            type: string
            pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
        - name: yId
          in: path
          required: true
          schema:
            type: string
            pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
        - name: zId
          in: path
          required: true
          schema:
            type: string
            pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
      requestBody:
        required: true
        content:
          application/vnd.api+json:
            schema:
              $ref: '#/components/schemas/Request'
      responses:
        "200":
          description: OK
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/Response'

  
components:
  schemas:
    Request:
      type: object
      properties:
        data:
          type: object
          properties:
            type:
              type: string
            id:
              type: string
              pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
    
    Response:
      type: object
      properties:
        links:
          type: object
          properties:
            self:
              type: string
        data:
          $ref: '#/components/schemas/Data'
    
    Data:
      type: object
      properties:
        type:
          type: string
        id:
          type: string
          pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
          
    GeometryError:
      type: object
      required:
        - code
        - status
        - title
      properties:
        id:
          type: string
          pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
        status:
          type: string
          example: 400
        title:
          type: string
        detail:
          type: string
        meta:
          type: object      
  
  
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

Answer 1

使用此模式定义架构：

components:
  schema:
    UUID:
      type: string
      format: uuid  # for tools/codegens that have built-in support for UUIDs
      pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'

然后您可以从其他架构和参数定义中引用此架构：

      parameters:
        - name: xId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/UUID'   # <-----
        - name: yId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/UUID'   # <-----
...

  schemas:
    Request:
      type: object
      properties:
        data:
          type: object
          properties:
            type:
              type: string
            id:
              $ref: '#/components/schemas/UUID'   # <-----