OpenAPI 3 Parameter Object it’s totally different from old OpenAPI 2. It gives the power to describe complex parameters, using the power of Schema object. I will introduce to you this breaking changes
One of the major changes is that body parameters (forms, json, …) are moved to a new object called
RequestBody. So now
Parameter supports only request parameters
- and the new one
In OpenAPI 2 a parameter is defined as:
In OpenAPI 3 you can find the same parameter as:
The major difference is that now you have to define a
schema for every single parameter, even the most simple.
It seems annoying, but It gives some interesting opportunities. For example: A model identifier has a particular regular expression (
format) that describes it and you want to write CRUD methods for this model. This is what you have to do in OpenAPI 2:
# get path
Now with OpenAPI 3 you can define this single string as a schema and reference to it where you want:
# define your identifier schema in components/schema
You can also reuse it to define complete model:
This is tricky, but actually it’s possible. With Schema object support you can define object as query, header, cookie, path parameter. This is an example:
I will explain later how to submit this type of requests
One interesting usage is when you have multi-dimensional key for a model, for example a geolocation model.
style is the new name of
collectionFormat field. But It isn’t only a name change. Also
style is supported by another field:
exploded. This is the comparison table with OpenAPI 2
For more informations about how to use this two new fields, check out this table.
If you think
schema isn’t enough, check out
content field. I will explain this further when I will cover
- Try to keep parameters as simple as possible. Avoid as much as possible objects and arrays, They create only a lot of headaches
queryparameters if you need to pass arrays to operation and use
- Pass objects to an operation with
RequestBody, or split it in different primitive parameters.
- Take as much as possible advantage of
Parameterobject. In particular use it to define object identifiers