Как указать подмножество свойств модели в документации по маршруту API swagger

Работаю над написанием спецификации API для моего сервиса с помощью swagger. Я использую определение модели ("#/definitions/prototype") в качестве параметра тела маршрутов POST /prototypes и PATCH /prototypes/:id.

Как указать, что маршрут 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

swagger swagger-2.0 swagger-editor
person Casey Flynn    schedule 30.03.2016    source источник

Ответы (1)


arrow_upward
2
arrow_downward

Swagger использует json-schema: http://json-schema.org $refs предоставляет вам возможность повторять существующие json-схема по новому пути. Обратите внимание, что вы используете $ref вместо patch/parameters/-name:prototype/schema. Вы можете создать новое определение только для патча в разделе определений и вместо этого ссылаться на него.

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
person tjmehta    schedule 30.03.2016