Swagger 2.0 - jak ustawić "jeden lub drugi" parametr wymagany?

Question

Mam zdefiniowany poniżej zasób SWAGER 2.0. Jak mogę wykonać "param1 lub param2"? Dzwoniący musi przekazać parametr param1 lub param2.

/some/res: 
put: 
    summary: some resource 
    responses: 
    200: 
     description: Successful response 
     schema: 
     $ref: '#/definitions/SomeResponse' 
    parameters: 
    - name: param1 
     type: string 
     description: param1 
     in: formData 
     required: false 
    - name: param2 
     type: string 
     description: param2 
     in: formData 
     required: false 

Answer 1

Specyfikacja OpenAPI (fka Swagger) nie obsługuje warunkowych lub wzajemnie wykluczających się parametrów (dowolnego typu).

Jest otwarty żądanej funkcji:
Support interdependencies between query parameters

Answer 2

Specyfikacja Swagger nie obsługuje wymóg warunkowego lub włączenie/wyłączenie parametrów.

To, co chciałbym zasugerować, to jasne określenie w opisie zasad dotyczących uwzględniania/wykluczania parametrów zapytania. Następnie za pomocą struktury sprawdzania poprawności, która zależy od Twojego języka (tj. Javax.validation for Java, restify-validation for restify itd.), Sprawdź poprawność parametrów.

Answer 3

w sekcji parametrów zależnych od Dokumenty Describing Parameters Swagger:

Swagger nieobsługującego zależności parametrów i wzajemnie wykluczające się parametry. Istnieje otwarte żądanie funkcji pod adresem https://github.com/OAI/OpenAPI-Specification/issues/256.

Od czerwca 2017 r. Ten numer miał 21 notowań, co czyni go trzecim najbardziej upominanym problemem w projekcie.

Answer 4

szczególny scenariusz w tej kwestii - żądanie POST/PP/patch z korpusu formy transmisji danych, który zawiera zarówno param1 lub param2 - może być określona przy użyciu OpenAPI 3.0 i oneOf:

openapi: 3.0.0 
... 

paths: 
    /some/res: 
    put: 
     requestBody: 
     required: true 
     content: 
      application/x-www-form-urlencoded: 
      schema: 
       oneOf: 
       - type: object 
        properties: 
        param1: 
         type: string 
        required: 
        - param1 
        additionalProperties: false 
       - type: object 
        properties: 
        param2: 
         type: string 
        required: 
        - param2 
        additionalProperties: false 

Uwaga dla Swagger Użytkownicy interfejsu użytkownika: formularzowy interfejs użytkownika i przykładowy rendering dla oneOf schematów are not available dla definicji OpenAPI 3.0.