Ponowne użycie modelu z różnymi wymaganymi właściwościami

Question

Mam ścieżkę, która używa złożonych modeli o prawie identycznych właściwościach dla każdej metody http. Problem polega na tym, że chcę zdefiniować pewne wymagane właściwości dla żądania PUT i POST, podczas gdy w odpowiedzi GET nie są wymagane żadne właściwości (ponieważ serwer zawsze zwraca wszystkie właściwości i jest wspomniany w innym miejscu w dokumentacji).

Stworzyłem prosty API dla kotów, aby pokazać, co próbowałem. Chodzi o to, że w przypadku odpowiedzi GET model odpowiedzi nie ma niczego oznaczonego jako wymagane, ale żądanie PUT musi mieć nazwę dla kota.

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 redaktor mówi, że jest to ważna specyfikacja, ale name jest ustawiona jako wymagana zarówno GET i PUT. To samo dotyczy interfejsu użytkownika Swagger.

Próbowałem również wersję PutCat:

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

Ale teraz wszystko jest opcjonalne.

Nie mogę tego obliczyć. Czy istnieje sposób, aby to zrobić właściwie?

EDIT:

Jak Helen poprawnie wspomniano, mogę używać readOnly rozwiązać ten konkretny przypadek z GET i PUT.

Ale powiedzmy, że dodaję właściwość breed, która musi być dostarczona (oprócz właściwości name) dla PUT. Następnie dodaję metodę PATCH, która może być użyta do aktualizacji breed lub name, podczas gdy druga pozostanie niezmieniona, a ja nie chcę ustawiać żadnej z nich jako wymaganych.

Answer 1

W tym przykładzie można użyć pojedynczego modelu zarówno dla GET, jak i POST/PUT, z właściwościami używanymi tylko w odpowiedzi GET oznaczonej jako readOnly. Od spec:

readOnly

Deklaruje właściwość jako "tylko do odczytu". Oznacza to, że MOŻE być wysłany jako część odpowiedzi, ale NIE MOŻE być wysyłany jako część żądania. Właściwości oznaczone jako readOnly being true NIE POWINNY znajdować się na wymaganej liście zdefiniowanego schematu. Wartością domyślną jest fałsz.

Spec wyglądałby następująco:

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 

Oznacza to, że trzeba umieścić name i breed:

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

i GET /cats/{id} musi zwrócić name i breed a także może zwrócić id :

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