OpenAPI 3 - свойство необязательно при написании, но обязательно при чтении - PullRequest
Новая
       6

OpenAPI 3 - свойство необязательно при написании, но обязательно при чтении

0 голосов
/ 04 марта 2019

Мой ресурс имеет идентификатор (типичный случай).

Он также имеет slug , понятный человеку, но все же уникальный идентификатор (в основном, для украшения URL).

Этот slug является необязательным при создании ресурса.Если клиент предоставляет один, он используется;в противном случае сервер сгенерировал его.

Однако этот slug требуется при чтении ресурса.

Мы хотим, чтобы это различие былоясно, поэтому любой инструментарий, читающий спецификацию OpenAPI, точно знает, чего ожидать.

Этого, конечно, можно достичь, используя сочетание различных схем, связанных с модификаторами allOf (см. пример ниже), но я бы хотелИзбегайте выполнения этой композиции (при условии, что она в первую очередь работает с инструментами).

Поэтому мой вопрос:

Есть ли способ в OpenAPI> = 3.0.2объявить свойство required-readOnly и необязательно-writeOnly?

Решение с использованием композиции: 

openapi: 3.0.2
info:
  title: Person API
  version: 1.0.0

paths: 
  '/persons/{person-slug}':
    get:
      parameters:
        - $ref: '#/components/parameters/PersonSlug'
      responses:
        200:
          description: Information on a person.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SlugRead'
                  - $ref: '#/components/schemas/Person'
    post:
      parameters:
        - $ref: '#/components/parameters/PersonSlug'
      responses:
        200:
          description: Information on a person.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SlugWrite'
                  - $ref: '#/components/schemas/Person'

components:

  parameters:

    PersonSlug:
      name: 'person-slug'
      description: Human readable unique ID of a person.
      required: true
      in: path
      schema:
        type: string

  schemas:

    SlugRead: # required
      required:
        - slug
      properties:
        slug:
          type: string
          readOnly: true

    SlugWrite: # not required
      properties:
        slug:
          type: string

    Person:
      required:
        - first_name
        - last_name
        - birth_date
      properties:
        first_name:
          type: string
        last_name:
          type: string
        birth_date:
          type: string
          format: date

1 Ответ

0 голосов
/ 05 марта 2019

Не могу понять, как добиться точно того, что вам нужно, возможно, но я думаю, что эффект можно определить, используя отдельные поля для желаемого (только для записи) по сравнению с назначенным (только для чтения) слагом: 

Person:
  required:
    - first_name
    - last_name
    - birth_date
    - assigned_slug
  properties:
    first_name:
      type: string
    last_name:
      type: string
    birth_date:
      type: string
      format: date
    assigned_slug:
      type: string
      readOnly: true
    desired_slug:
      type: string
      writeOnly: true

Не знаю, будет ли какой-нибудь инструмент работать с ним правильно, хотя!

...