Swagger; określić dwie odpowiedzi z tego samego kodu w oparciu o opcjonalny parametr

Question

To pytanie nie jest duplikatem (Swagger - Specify Optional Object Property or Multiple Responses) dlatego, że PO próbuje powrócić 200 lub 400.

mam GET z opcjonalnym parametrem; np. GET /endpoint?selector=foo.

Chcę wrócić 200, którego schemat jest inny na podstawie tego, czy parametr został przekazany, np ,:

GET /endpoint -> {200, schema_1} 
GET /endpoint?selector=blah -> {200, schema_2} 

W YAML, próbowałem posiadające dwa 200 kodów, ale widz zgniecie je jako gdybym tylko podał jeden.

Czy istnieje sposób, aby to zrobić?

Edycja: Wydaje związane następujące: https://github.com/OAI/OpenAPI-Specification/issues/270

Answer 1

chciałem to samo, i wpadłem na obejście, które wydaje się działać:

Ive właśnie zdefiniowano dwie różne ścieżki:

/path: 
(...) 
     responses: 
     200: 
      description: Sucesso 
      schema: 
      $ref: '#/definitions/ResponseOne' 
(...) 

/path?parameter=value: 
(...) 
     responses: 
     200: 
      description: Sucesso 
      schema: 
      $ref: '#/definitions/ResponseTwo' 
(...) 

Ścieżki działają na edytorze przekrętów. Mogę nawet udokumentować każdą opcję w inny sposób i umieścić opcjonalne parametry, które tylko mogą znajdować się w drugim przypadku, co sprawia, że ​​dokumentacja API jest znacznie czystsza. Używając operationId możesz generować czystsze nazwy dla wygenerowanych metod API.

Opublikowałem tutaj to samo rozwiązanie (https://github.com/OAI/OpenAPI-Specification/issues/270), aby sprawdzić, czy brakuje mi czegoś więcej.

Rozumiem, że nie jest to wprost dozwolone/zalecane (ani nie znalazłem jakiegoś miejsca, które wyraźnie zabroniłoby tego). Ale jako obejście i bycie jedynym sposobem dokumentowania interfejsu API z tym zachowaniem w bieżącej specyfikacji, wygląda jak opcja.

dwa problemy Ive znaleziono się z nim:

• kod Java gen URL ucieka Znak „=”, w związku z czym nie będzie działać, chyba to naprawić w wygenerowanego kodu. Prawdopodobnie dzieje się tak w innych generatorach kodu .
• Jeśli masz więcej zapytań, to dodasz dodatkowe "?" i zawieść;

Jeśli nie są to blokery, to przynajmniej pozwoli ci to odpowiednio udokumentować takie przypadki i pozwolić na testowanie za pomocą edytora wychwytu.

Answer 2

OpenAPI 3.0 pozwala korzystać oneOf zdefiniować wiele możliwości żądania organów lub organów reagowania na tej samej operacji:

openapi: 3.0.0 
... 
paths: 
    /path: 
    get: 
     responses: 
     '200': 
      description: Success 
      content: 
      application/json: 
       schema: 
       oneOf: 
        - $ref: '#/components/schemas/ResponseOne' 
        - $ref: '#/components/schemas/ResponseTwo' 

Jednakże, nie jest to możliwe do mapowania konkretne odpowiedzi na konkretne wartości parametrów. Będziesz musiał dokumentować te szczegóły ustnie w description.