search

open-api-spex / open_api_spex

Open API Specifications for Elixir Plug applications
Mozilla Public License 2.0
681 stars 177 forks source link

Add a `--check` flag to `mix openapi.spec.json` and `mix openapi.spec.yaml` #617

Closed zachdaniel closed 3 days ago

zachdaniel commented 6 days ago

It would be great to be able to simply add a step to CI endpoints that called mix openapi.spec.json ... --check that would fail with a nice error message if the spec does not match what would be generated.

zachdaniel commented 5 days ago

Original discussion in ash_json_api: https://github.com/ash-project/ash_json_api/pull/200

zorbash commented 5 days ago

@zachdaniel Can you elaborate on the problem such a task would solve? My assumption is that you want to commit an open-api.yaml file and use --check that it's up-to-date. Why would you not generate the spec in a CI step and perhaps upload it as an artefact instead (or include it in the ex_doc generated docs)?

zachdaniel commented 5 days ago

Often I prefer to have the artifacts like this committed into the repo. Adding a --check flag verifies that the committed spec file is correct, ensuring that the developer regenerates the file and commits again. This also allows people to review diffs in generated api specifications to look for things like potentially breaking changes etc.

zachdaniel commented 5 days ago

For additional context: in Ash both the file and the api are generated for you. So you don't get a diff of even the open api specification in your code base.