Use OpenAPI to Prevent Unintended Changes
OpenAPI is brilliant, it’s a specification for your restful API!
Your customers can create clients to talk to your system. Your documentation probably improved while implementing it. Because you had to revisit all public endpoints and update its information. The documentation and code is living in the same repository. This makes it easier to remember to update the documentation when you make changes to the code. There is hopefully a stronger sense of ownership of the documentation from the developers point of view.
Another perk is that you can use it to prevent unintended changes in your API via integration testing!
The idea is:
- Generate your specification
- Compare with a reference specification
- If there are no diffs, the test passes! ✔
- If the diff is intentional, update the reference to the current state and commit. If it’s not, then you avoided an unintended API change. 👌
You’ll have to take an active decision when making changes that affects the specification.
This doesn’t test the endpoints themselves of course, but it’s a start towards a little bit safer CI/CD!
