At the scale of nginx, having automatic verification that the examples (and the output of the API in general) match the specification would be great.
At our scale, here is what really helped me go through the rework (and ensure we do not regress too easily):
- setting additionalProperties to "false" to detect key field "rot"
- using "required: [x,y,z]" on everything, and by default specify "all the property keys", with an opt-out (so that each time a developer adds a field later, it is considered mandatory, unless otherwise specified)
- use tooling during the tests: "assert_schema" (with OpenAPISpex) to ensure our API endpoints responses pass the spec (additionalProperties: false helps ensure we get an exception in case of key field rot, again!)
It can be super frustrating for users to live with the uncertainty of the response of an API for sure, and I was happy to discover the Elixir tooling (OpenAPISpex in particular) worked so nicely once I understood what I had to do.
AFAIK this is just a frontend Postman replacement which also supports OpenAPI, no idea how much it differs from showing the underlying type support from OpenAPI specs tho, seems to use collections so probably accepts postman ones to import. dunno just saw the other day on show hn
Having gone through a pretty heavy overhaul of an "OpenAPI" (full code in Elixir at https://github.com/etalab/transport-site/pull/3351), I stumbled on that exact type of problem!
At the scale of nginx, having automatic verification that the examples (and the output of the API in general) match the specification would be great.
At our scale, here is what really helped me go through the rework (and ensure we do not regress too easily):
- setting additionalProperties to "false" to detect key field "rot"
- using "required: [x,y,z]" on everything, and by default specify "all the property keys", with an opt-out (so that each time a developer adds a field later, it is considered mandatory, unless otherwise specified)
- use tooling during the tests: "assert_schema" (with OpenAPISpex) to ensure our API endpoints responses pass the spec (additionalProperties: false helps ensure we get an exception in case of key field rot, again!)
- even more useful: crawl our production most important endpoints and tweak the spec until everything is green (an example of useful use of Task.async_stream in Elixir, by the way) https://github.com/etalab/transport-site/pull/3351/files#dif...
It can be super frustrating for users to live with the uncertainty of the response of an API for sure, and I was happy to discover the Elixir tooling (OpenAPISpex in particular) worked so nicely once I understood what I had to do.