How should someone document an API

Instructions: Generate API program code from the OpenAPI documentation

Admittedly, OpenAPI documentation does not turn into a finished API completely by magic, and a code generator does not make developers superfluous either. Such a generator can relieve you of a lot of hard work. In the classic way, you first write the code and then manage to document the finished API. The approach is called "Code First" and it is suitable if someone asks for the documentation only after completion. The most widely used standard for API documentation for REST APIs is called OpenAPI, the documentation is formulated in YAML format. There is some generator support for the code first approach. Then relevant functions in the code are provided with comment blocks and a parser turns them into OAS documentation.

API first

The opposite approach, ie "API First", has also become popular. Without even writing a line of code, the requirements for the API are recorded in an OAS description.

Not starting with the programming directly, but first documenting the API in a YAML file, sounds terribly cumbersome and unfamiliar to many. However, the approach offers many advantages: Those who work in larger teams or companies will not be able to avoid agreeing with the client and colleagues on exactly how the API should be built. An OpenAPI description offers a neutral, programming language-independent and comparatively easy-to-read option.