The code-first approach implements an API from business requirements, then generates its OpenAPI definition from the application code. That definition can drive client SDKs and API reference documentation. section 6.3
A practical code-first workflow is:
- Implement the required API behavior and any changes that should appear in its reference documentation. section 6.3
- Generate an OpenAPI definition from the implementation. section 6.3
- Inspect the generated schema and examples; compare the result with the design-phase source of truth when one exists. section 6.3.2
- Fix differences or use the definition to produce consumer-facing artifacts such as SDKs and reference documentation. section 6.3 section 6.3.2
Prototype before design commitment
A team can prototype an API in code to uncover technology constraints and requirements, generate an OpenAPI definition from that prototype, and use the result to refine the design. This exploratory workflow blurs the usual boundary between code-first and design-first development. section 6.3.2
Code-first is quick for simple API changes and familiar to developers who move directly from requirements to implementation. Its risk is functional delivery without sufficient attention to usability and consistency from the consumer’s perspective. section 1.5.1
