swagger APIルートドキュメントのモデルプロパティのサブセットを指定する方法

Question

swaggerを使用してサービスのAPI仕様を作成するための作業。私はPOST /prototypesとPATCH /prototypes/:idルートのボディパラメータとしてモデル定義（ '＃/ definitions/prototype'）を使用しています。

PATCHルートは、POSTルートが実行する要求の本体内のプロパティのサブセットのみを受け入れるように指定しますか？たとえば、PATCH /instances/:idルートには、mobileDeviceIdプロトタイププロパティの変更のみを許可します。

swagger: "2.0" 
info: 
    title: "" 
    description: "" 
    version: "1.0.0" 
host: foo.example.com 
schemes: 
    - https 
basePath: /v1 
produces: 
    - application/json 
consumes: 
    - application/json 
paths: 
    /prototypes: 
    post: 
     summary: Create new prototype 
     parameters: 
     - name: prototype 
      in: body 
      description: Prototype object 
      required: true 
      schema: 
      $ref: "#/definitions/Prototype" 
     responses: 
     201: 
      description: Success 
      schema: 
      $ref: "#/definitions/SuccessCreated" 
     403: 
      description: Prototype limit exceeded error 
      schema: 
      $ref: "#/definitions/Error" 
     default: 
      description: Unexpected error 
      schema: 
      $ref: "#/definitions/Error" 
    /prototypes/{id}: 
    patch: 
     summary: Update an existing prototype's properties 
     parameters: 
     - name: id 
      in: path 
      type: number 
      description: ID property of a prototype 
      required: true 
     - name: prototype 
      in: body 
      description: Prototype object 
      required: true 
      schema: 
      $ref: "#/definitions/Prototype" 
     responses: 
     200: 
      description: Success 
definitions: 
    Prototype: 
    type: object 
    properties: 
     id: 
     type: integer 
     format: int64 
     name: 
     type: string 
     mobileDeviceId: 
     type: number 
    SuccessCreated: 
    type: object 
    description: Returned as response to successful resource create request 
    properties: 
     code: 
     type: number 
     default: 201 
     message: 
     type: string 
    Error: 
    type: object 
    properties: 
     code: 
     type: integer 
     format: int32 
     message: 
     type: string 
     fields: 
     type: string 

Answer 1

威張っは、JSONスキーマを使用しています：http://json-schema.org $ref sが新しいパスに存在するJSONスキーマを繰り返す方法/ wをご提供します。 patch/parameters/-name:prototype/schemaに$refを使用していることに注意してください。 定義セクションにパッチ用の新しい定義を作成し、それを代わりに参照することができます。

swagger: "2.0" 
info: 
    title: "" 
    description: "" 
    version: "1.0.0" 
host: foo.example.com 
schemes: 
    - https 
basePath: /v1 
produces: 
    - application/json 
consumes: 
    - application/json 
paths: 
    /prototypes: 
    post: 
     summary: Create new prototype 
     parameters: 
     - name: prototype 
      in: body 
      description: Prototype object 
      required: true 
      schema: 
      $ref: "#/definitions/Prototype" 
     responses: 
     201: 
      description: Success 
      schema: 
      $ref: "#/definitions/SuccessCreated" 
     403: 
      description: Prototype limit exceeded error 
      schema: 
      $ref: "#/definitions/Error" 
     default: 
      description: Unexpected error 
      schema: 
      $ref: "#/definitions/Error" 
    /prototypes/{id}: 
    patch: 
     summary: Update an existing prototype's properties 
     parameters: 
     - name: id 
      in: path 
      type: number 
      description: ID property of a prototype 
      required: true 
     - name: prototype 
      in: body 
      description: Prototype object 
      required: true 
      schema: 
      $ref: "#/definitions/PatchPrototype" 
     responses: 
     200: 
      description: Success 
definitions: 
    Prototype: 
    type: object 
    properties: 
     id: 
     type: integer 
     format: int64 
     name: 
     type: string 
     mobileDeviceId: 
     type: number 
    PatchPrototype: 
    type: object 
    properties: 
     mobileDeviceId: 
     type: number 
    SuccessCreated: 
    type: object 
    description: Returned as response to successful resource create request 
    properties: 
     code: 
     type: number 
     default: 201 
     message: 
     type: string 
    Error: 
    type: object 
    properties: 
     code: 
     type: integer 
     format: int32 
     message: 
     type: string 
     fields: 
     type: string