web-dev-qa-db-ja.com

一部の操作に必要な定義にフィールドを作成し、他の操作には必要としない方法

スワッガーの定義をyamlで書いています。このような定義があるとしましょう。

paths:
  /payloads:
    post:
      summary: create a payload
      ...
      parameters:
      - in: body
        name: payload
        description: New payload
        required: true
        schema:
          $ref: "#/definitions/payload"
    put:
      summary: update a payload
      ...
      parameters:
      - in: body
        name: payload
        description: Updated existing payload
        required: true
        schema:
          $ref: "#/definitions/payload"
...
definitions:
  payload:
    properties:
      id:
        type: string
      someProperty:
        type: string
      ...

ペイロードのidプロパティがPUT操作に必須であり、POST操作ではオプション（またはまったく表示されない））であることを示す方法はありますか？

swaggerswagger-2.0swagger-editor
19
Joseph Downing

モデルを個別に定義する必要があります。

ただし、除外と差異の場合のオプションがあります。

除外する場合（簡単なケース）は、excludeプロパティを使用してのモデルを作成します（例：ModelA）。次に、ModelBをModelAと追加のプロパティとして定義します。

ModelB:
  allOf:
    - $ref: "#/definitions/ModelA"
    - type: object
      properties:
        id:
          type: string

違いを定義する場合は、上記と同じ方法に従い、idをModelAから除外します。次に、ModelBとModelCを拡張ModelAとして定義し、それぞれに独自の制限があるidプロパティを追加します。念のために言っておきますが、JSONスキーマを使用すると、上記の元の例に従って、定義を「オーバーライド」できる場合があります。ただし、これは実際にはオーバーライドではなく、単純な間違いをしないようにJSONスキーマの概念をよりよく理解する必要があるため、今のところこのパスを使用することをお勧めします。

18
Ron

これを実行する私の方法は、すべてのパラメーターを含む「抽象」モデルを定義することです。次に、ユースケースごとに、最初のモデルを参照し、必須フィールドを正確に示すモデルを定義します。

paths:
  /payloads:
    post:
      summary: create a payload
      ...
      parameters:
      - in: body
        name: payload
        description: New payload
        required: true
        schema:
          $ref: "#/definitions/NewPayload"
    put:
      summary: update a payload
      ...
      parameters:
      - in: body
        name: payload
        description: Updated existing payload
        required: true
        schema:
          $ref: "#/definitions/UpdatePayload"
...
definitions:
  # This payload would be used with update requests and has no required params.
  NewPayload:
     allOf:
       - { $ref: '#definitions/PayloadProperties }
       - type: object

  # This payload would be used with update requests and require an id param.
  UpdatePayload:
     allOf:
       - { $ref: '#definitions/PayloadProperties }
       - type: object
         required: [id]

  PayloadProperties:
    properties:
      id:
        type: string
      someProperty:
        type: string
      ...

この方法は、複製を必要とせず、関心の分離と粒度を提供するため、かなりクリーンだと思います。

0
AlexGordon

私は今、同じ問題を抱えています。私の場合、モデルのrequeridブロックをオーバーライドしようとしました。しかし、うまくいきませんでした。 = [次に、$ refの新しいプロパティを追加できることを思い出しました。したがって、各メソッドのスキーマで必須フィールドを定義すると機能します。このようなもの（各参照に必要なブロックに焦点を当てる）：

swagger: '2.0'
info:
  title: API
  version: 0.0.1
Host: api.help.v1
basePath: /help
schemes:
- https
definitions:
  MyModel:
    description: 'Exemplo'
    type: object
    properties:
      field_1:
        type: string
      field_2:
        type: string
      field_3:
        type: string
paths:
  '/helps':
    post:
      description: ''
      summary: ''
      parameters:
        - in: body
          name: payload
          schema:
            type: object
            allOf:
            - $ref: '#/definitions/MyModel'
            required: 
            - field_1
      responses:
        '200':
          description: OK
        '400':
          description: N_OK
    put:
      description: ''
      summary: ''
      parameters:
        - in: body
          name: payload
          schema:
            type: object
            allOf: 
            - $ref: '#/definitions/MyModel'
            required: 
            - field_2
      responses:
        '200':
          description: OK
        '400':
          description: N_OK

externalDocs:
  description: Find out more about Swagger
  url: 'http://swagger.io'

ああ！ Swaggerエディターで、モデルビューによってのみ表示されます： enter image description here

まだ試していません。しかし、そのようなモデルを定義することは可能であるはずです。

0
Akostha