|
|
|
|
|
|
by crypteasy
2012 days ago
|
|
|
My company is currently trialing this with the Open API Spec. The workflow at a high level: 1) Make code changes to a specific microservice.
(note: The Open API Spec also lives in code.) 2) CI/CD pipelines get triggered. 3) New microservice is built. 4) Call every REST endpoint defined in the microservice's Open API Spec and validate it using the example requests/responses. 5) If successful, regenerate the API documentation from the Open API Spec. This ensures that our documentation and services will stay inline with each other. |
|
|
It's somewhat specific to golang but so far it has been relatively good for us.
The spec is directly next to the code as code comments, so it has far more chances to get updated when changes are made compared to an external documentation.
Also, the payloads and responses are directly derived from the Golang structs, so, at least on that aspect, changes in the code are automatically reflected in the spec (apart for description and examples).
We also put the interactive documentation directly in our API under /doc. It is a useful tool for developers when implementing a new url/handler or modifying an existing one. It also creates incentives to keep the documentation matching.
Overall, we had very few mismatches between the spec and the actual implementation overall, despite not having deeply tested it (be it manually or automatically). Apart from one or two mismatches that were fixed quickly, I was able to take the spec, generate client libraries from it (swagger-codegen), and use them for quite extensive demos without issues.
We are still early in the project (not in production yet), and there are definitely some aspects we need to improve (integration/automated tests to be sure doc and code are 100% matching) or to completely figure out (ex: how to handle several versions of the same API). But overall, using swaggo/swag has been a pleasant experience.