異なる必要なプロパティを持つモデルを再利用する

Question

私は、httpメソッドごとにほとんど同じプロパティを持つ複雑なモデルを使用するパスを持っています。問題は、をのPUTとPOSTの要求に必要なプロパティを定義したいが、GETレスポンスではプロパティは必要ないということです（サーバーは常にすべてのプロパティを返し、ドキュメントのどこかで言及しています）。

シンプルなcat 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" 

闊歩エディタはこれが有効な仕様であることを述べているが、GETやPUTの両方のために必要とされるnameが設定されています。 SwaggerのUIも同じです。

私もPutCatの次バージョン試してみました：

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

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

私はこれを理解できません。これを正しく行う方法はありますか？

EDIT：正しく述べ

Helenとして、私は、GETやPUTと、この特定のケースを解決するためにreadOnlyを使用することができます。

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

Answer 1

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

readOnly

は、 "読み取り専用" としてプロパティを宣言します。これは、応答の一部として送信されるかもしれないが、要求の一部として送信されてはならないことを意味する。 trueであるとreadOnlyとしてマークされたプロパティは、定義されたスキーマの必須リストに存在してはならない（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を置く必要があります意味：

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

とGET /cats/{id}nameとbreedを返す必要があり、また、idを返すことがあります。 ：

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