20

I have created a RESTful API, and I am now defining the Open API 3.0 JSON representation for the usage of this API.

I am requiring usage of a parameter conditionally, when another parameter is present. So I can't really use either required: true or required: false because it needs to be conditional. Should I just define it as required: false, and then in the summary and / or description say that it is required when the other parameter is being used? Or is there a way of defining dependency between parameters? I haven't found anything in the specs that mention a case like this.

JohnRDOrazio
  • 1,358
  • 2
  • 15
  • 28
  • 3
    Parameter Dependencies OpenAPI 3.0 does not support parameter dependencies and mutually exclusive parameters. There is an open feature request at https://github.com/OAI/OpenAPI-Specification/issues/256. What you can do is document the restrictions in the parameter description and define the logic in the 400 Bad Request response. For example, consider the /report endpoint that accepts either a relative date range (rdate) or an exact range (start_date+end_date): - For more info - https://swagger.io/docs/specification/describing-parameters/ – rootkonda Aug 01 '20 at 20:22
  • ok thanks, you could post it as an answer, the issue you referenced is exactly what I was looking for. I see I'm not the only one requesting this and I see a [mention was in fact made in the documentation](https://swagger.io/docs/specification/describing-parameters/#dependencies) – JohnRDOrazio Aug 01 '20 at 23:18
  • I added it as an answer. – rootkonda Aug 02 '20 at 07:29

2 Answers2

11

From the docs:

Parameter Dependencies

OpenAPI 3.0 does not support parameter dependencies and mutually exclusive parameters. There is an open feature request at github.com/OAI/OpenAPI-Specification/issues/256. What you can do is document the restrictions in the parameter description and define the logic in the 400 Bad Request response.

JohnRDOrazio
  • 1,358
  • 2
  • 15
  • 28
rootkonda
  • 1,700
  • 1
  • 6
  • 11
6

See https://community.smartbear.com/t5/Swagger-Open-Source-Tools/Defining-conditional-attributes-in-OpenAPI/td-p/222410 where you can use anyOf around the required list of field

anyOf:
       - required: [longitude, latitude]
       - required: [postalCode, countryCode]
       - required: [city, state, countryCode]
Laurent Picquet
  • 69
  • 1
  • 2