Biçimlendirici API yol belgelerinde model özelliklerinin alt kümesi nasıl belirtilir?

Question

Servisim için bir spp. POST /prototypes ve PATCH /prototypes/:id yollarının gövde parametresi olarak bir model tanımı ('#/define/prototype') kullanıyorum.

PATCH yolunun yalnızca POST yolunun yaptığı isteğin gövdesindeki özelliklerin bir alt kümesini kabul ettiğini nasıl belirtirsiniz? Örneğin, PATCH /instances/:id yolunun yalnızca mobileDeviceId prototipleri özelliğinin değiştirilmesine izin vermesini istiyorum.

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

Swagger json-şemayı kullanır: http://json-schema.org $ref ler yeni bir yol mevcut olan json-şema tekrarlamak için bir yol w/sunuyoruz. patch/parameters/-name:prototype/schema için $ref kullandığınıza dikkat edin. Tanımlar bölümünde yalnızca düzeltme eki için yeni bir tanım oluşturabilir ve bunun yerine

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