A code-first approach generates or maintains an OpenAPI document from implementation code, typically beginning with controllers and data models rather than an independent specification. It can still support design-first work, but directly coding an API without design risks costly changes after consumption. section 6.2.1
Choose it by weighing its implementation alignment against its design and maintenance costs:
- Keeps OpenAPI aligned with the implementation and can use convenient framework-native annotations. section 6.2.2
- May expose implementation details, require early stack selection, or produce incomplete documentation when frameworks lack OpenAPI features. section 6.2.2
- Requires monitoring because implementation changes can go unnoticed without an independent description of the expected API. section 6.2.2
Retro-documenting an existing API
Add an OpenAPI library to an existing implementation to generate a quick description of its operations and successful output data. Treat the result as useful but not necessarily exhaustive documentation. section 6.2.1
Figure 6.6 When deciding between specification-first and code-first approaches, it’s essential to check the pros and cons of each approach in the context in which you work.
Compare specification-first and code-first approaches against the context, constraints, and capabilities of the API team. section 6.2.2
