4

如果我们查看消息 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 定义 2 个定义（Message 和 UpdatedMessage）
  • 不使用 PATCH 方法或 GET/POST 方法中的定义

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

我不知道这是否可能。

谢谢

4

1 回答 1

1

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

  • 一个UpdateMessage包含所有属性，除了external_id
  • 包含Message所有UpdateMessage属性加上external_idusingallOf是使用 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"
于 2016-07-23T10:59:16.920 回答