Design-first has many benefits for rapid prototyping and shaping ideas. However, code-first is probably the more mature of the two design methodologies discussed in this chapter. The reason for this is quite simple: Implementation code predated API description languages, which in turn were born from the need to produce a schematic representation of an API for consumption outside the code base. The API economy and software engineering in general have had this need for a long time. We cannot simply throw open our code repositories and invite any external collaborators in to view our implementation code. We need the means to describe the shape of our API outside our safe and secure codebase. That fact is true regardless of whether we are going with code-first or design-first, but it's all the more pertinent in the code-first world. The reason that API description languages came into being is so that developers could automatically generate API-related documentation based on the shape of their implementation code and provide the description to external consumers.

The methodology is generally as follows:

Write implementation code that reflects a given interaction with the API.
Implement routing to provide request and response operations.
Apply meaningful annotations that can transpose the "shape" of the code to an API description document.
Generate the API description document at build time, source control it, and distribute the document to interested parties.
This approach has grown organically, matured over time, and is not unique to OpenAPI. There is also a huge number of packages that support code-first. We have two examples in the following sections that use springdoc-openapi and APIFlask, written in Java and Python respectively, to demonstrate how code-first works with popular programming languages and frameworks. In both examples, we will use the stripped-down Petstore API we created in the design-first section as the implementation requirement, and show how this OpenAPI description would be generated from code.