在 swagger 2.0 (openapi) 中，如何在 POST 和 PUT 请求之间有不同的资源定义？

Question

如果我们查看一条消息API（例如）我希望它能够

创建消息
收到消息
更新消息

消息包含外部引用（来自消费者的唯一 ID）

此 external_id 应在创建时使用 POST 请求设置
这个 external_id，无法用 PATCH

实现它的解决方案是什么？

一个API样本：

swagger: '2.0'

host: api.com
basePath: /v2
schemes:
  - https

info:
  title: dummy
  version: 1.0.0

consumes:
  - application/json

produces:
  - application/json


paths:
  /messages:
    post:
      summary: Create a message
      parameters:
        - name: message
          in: body
          required: true
          schema:
            $ref: '#/definitions/Message'

      responses:

        201:
          description: Ok
          schema:
            $ref: '#/definitions/Message'


  /messages/{id}:
    get:

      summary: "Get a message by ID"
      parameters:
        - name: id
          in: path
          description: The message ID
          required: true
          type: string
          format: uuid

      responses:

        200:
          description: OK - the message
          schema:
            $ref: '#/definitions/Message'

    patch:
      summary: Modify a message
      parameters:
        - name: id
          in: path
          description: The message ID
          required: true
          type: string
          format: uuid

        - name: message
          in: body
          required: true
          schema:
            $ref: '#/definitions/Message'

      responses:

        201:
          description: Ok
          schema:
            $ref: '#/definitions/Message'

definitions:

  Message:
    type: object
    required:
      - id
      - external_id
      - title
      - content
      - created_at

    properties:
      id:
        type: string
        readOnly: true

      external_id:
        type: string
        description: "Your own reference ID"

      title:
        type: string

      content:
        type: string

      created_at:
        type: string
        format: date-time
        readOnly: true

我看到的唯一解决方案：

使用 allOf
未使用 PATCH 方法或 GET/POST 方法中的定义

是否有更好的解决方案来实现这一点？理想的解决方案是只有一个 Message 定义，并在 PATCH 方法中覆盖 Message 定义（删除该字段）。

不知道可不可以

感谢

Answer 1

要处理此用例，您必须定义 2 条消息：

一个 UpdateMessage 包含除 external_id
包含所有 UpdateMessage 属性加上 external_id 使用 allOf 的 Message 是使用 OpenAPI (fka.Swagger) 2.0 版本实现此目的的唯一方法。

这是相应的 YAML：

swagger: '2.0'

host: api.com
basePath: /v2
schemes:
  - https

info:
  title: dummy
  version: 1.0.0

consumes:
  - application/json

produces:
  - application/json


paths:
  /messages:
    post:
      summary: Create a message
      parameters:
        - name: message
          in: body
          required: true
          schema:
            $ref: '#/definitions/Message'

      responses:

        201:
          description: Ok
          schema:
            $ref: '#/definitions/Message'


  /messages/{id}:
    get:

      summary: "Get a message by ID"
      parameters:
        - name: id
          in: path
          description: The message ID
          required: true
          type: string
          format: uuid

      responses:

        200:
          description: OK - the message
          schema:
            $ref: '#/definitions/Message'

    patch:
      summary: Modify a message
      parameters:
        - name: id
          in: path
          description: The message ID
          required: true
          type: string
          format: uuid

        - name: message
          in: body
          required: true
          schema:
            $ref: '#/definitions/UpdateMessage'

      responses:

        201:
          description: Ok
          schema:
            $ref: '#/definitions/Message'

definitions:

  UpdateMessage:
    type: object
    required:
      - id
      - title
      - content
      - created_at

    properties:
      id:
        type: string
        readOnly: true

      title:
        type: string

      content:
        type: string

      created_at:
        type: string
        format: date-time
        readOnly: true

  Message:
    allOf:
      - $ref: '#/definitions/UpdateMessage'
      - required:
          - external_id
        properties:
          external_id:
            type: string
            description: "Your own reference ID"

在 swagger 2.0 (openapi) 中，如何在 POST 和 PUT 请求之间有不同的资源定义？

In swagger 2.0 (openapi), how to have a different resource definition between POST and PUT request?

api

inheritance

swagger

openapi