В swagger 2.0 (openapi), как иметь другое определение ресурса между запросами POST и PUT?

Если мы посмотрим на API сообщений (например), я хочу, чтобы он мог

  • создать сообщение
  • получить сообщение
  • обновить сообщение

Сообщение содержит внешнюю ссылку (уникальный идентификатор от потребителя)

  • Этот 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

Единственные решения, которые я вижу:

  • определение 2 определений (Message и UpdatedMessage) с использованием allOf
  • не используя определение в методе PATCH или в методе GET/POST

Есть ли лучшее решение для достижения этого? Идеальным решением было бы иметь только одно определение Message и в методе PATCH переопределить определение Message (удалив поле).

Я не знаю, возможно ли это.

Спасибо


person nemenems    schedule 07.07.2016    source источник


Ответы (1)


Чтобы справиться с этим вариантом использования, вы должны определить 2 сообщения:

  • UpdateMessage, содержащий все свойства, кроме external_id
  • Message, содержащий все свойства UpdateMessage плюс external_id с использованием allOf, является единственным способом достижения этого с помощью версии 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"
person Arnaud Lauret    schedule 23.07.2016