API Spec to Code or Code to API Spec?

Source: OpenAPIHub

Few software engineers don’t like writing documentation. Some never did. Many tools have been created to create documentation from code, such as Doxygen, Godoc. It’s probably useful for implementation documentation that explains how a function should be used, e.g. Golang has the built-in document generator. However, for API services, I think the API-first approach should be preferred, for a few reasons:

1. It liberally forces us to think of API first — This is very important!
2. Once the API is ready, the API consumer and API provider can work concurrently.
3. Boilerplate code can be (re-)generated easily, taking away the tedious work from developers.
4. The implementation and API doc are in sync, which can be enforced by CI/CD.

I think the barrier to adopt this approach is quite low given the many tools available. If you haven’t tired it, I think you should and it can be a game changer.