web-dev-qa-db-ja.com

必要なプロパティが異なるモデルの再利用

各httpメソッドのプロパティがほとんど同じである複雑なモデルを使用するパスがあります。問題は、PUTおよびPOSTのリクエストにsome必要なプロパティを定義したいのですが、GET応答にはプロパティは必要ありません（サーバーは常にすべてのプロパティを返し、それが言及されているため）ドキュメントの別の場所）。

私が試したことを示すために、簡単な猫APIを作成しました。アイデアは、GET応答の場合、応答モデルには必要なものとしてマークされているものは何もないが、PUTの要求には猫の名前が必要であるということです。

swagger: "2.0"

info:
  title: "Cat API"
  version: 1.0.0

paths:
  /cats/{id}:
    parameters:
      - name: id
        in: path
        required: true
        type: integer
    get:
      responses:
        200:
          description: Return a cat
          schema:
            $ref: "#/definitions/GetCat"
    put:
      parameters:
        - name: cat
          in: body
          required: true
          schema:
            $ref: "#/definitions/PutCat"
      responses:
        204:
          description: Cat edited

definitions:
  Cat:
    type: object
    properties:
      name:
        type: string
  GetCat:
    allOf:
      - $ref: "#/definitions/Cat"
    properties:
      id:
        type: integer
  PutCat:
    type: object
    required:
      - name
    properties:
      $ref: "#/definitions/Cat/properties"

Swagger Editorによると、これは有効な仕様ですが、nameはGETとPUTの両方で必要に応じて設定されます。 Swagger UIについても同様です。

次のバージョンのPutCatも試しました。

PutCat:
  type: object
  required:
    - name
  allOf:
    - $ref: "#/definitions/Cat"

しかし、今ではすべてがオプションです。

これはわかりません。これを正しく行う方法はありますか？

編集：

Helen が正しく言及されているように、readOnlyを使用して、GETおよびPUTでこの特定のケースを解決できます。

しかし、PUTに（breedプロパティに加えて）提供する必要があるnameプロパティを追加するとします。次に、breedまたはnameのいずれかを変更せずに更新するために使用できるPATCHメソッドを追加し、必要に応じてどちらも設定しないようにします。

swaggeropenapi
21
NotNone

この例では、GETとPOST/PUTの両方に単一のモデルを使用できます。プロパティは、GET応答でのみ使用され、readOnlyとマークされます。 spec から：

readOnly

プロパティを「読み取り専用」として宣言します。これは、応答の一部として送信される場合がありますが、要求の一部として送信されてはならないことを意味します。 readOnlyがtrueとしてマークされているプロパティは、定義されたスキーマの必須リストに含まれるべきではありません（SHOULD NOT）。デフォルト値はfalseです。

仕様は次のようになります。

    get:
      responses:
        200:
          description: Return a cat
          schema:
            $ref: "#/definitions/Cat"
    put:
      parameters:
        - name: cat
          in: body
          required: true
          schema:
            $ref: "#/definitions/Cat"
      responses:
        204:
          description: Cat edited

definitions:
  Cat:
    properties:
      id:
        type: integer
        readOnly: true
      name:
        type: string
      breed:
        type: string
    required:
      - name
      - breed

つまり、nameとbreedをPUTする必要があります。

{
  "name": "Puss in Boots",
  "breed": "whatever"
}

およびGET /cats/{id}はnameおよびbreedを返す必要があり、idも返す場合があります。

{
  "name": "Puss in Boots",
  "breed": "whatever",
  "id": 5
}
23
Helen

同様の問題がありました。私のインデントが間違っていることが判明しました。次の構文が機能するはずです。

PutCat:
  allOf:
    - $ref: "#/definitions/Cat"
    - type: object
      required: [name]
2
AlexGordon