OpenAPI specification - API-first and code-first approaches

The timing of creating the OpenAPI specification can vary depending on your development process. Here are two common approaches: API-first development and code-first development.

API-First Development

In the API-first approach, the OpenAPI specification is created before the actual API code is written. This approach has several advantages:

1. Design Clarity: It forces you to think through the API design thoroughly before implementation, ensuring a well-thought-out structure and consistent endpoints.
2. Stakeholder Communication: It allows for early feedback from stakeholders, including frontend developers, other backend services, and business analysts, ensuring everyone is on the same page regarding API functionality and structure.
3. Parallel Development: Frontend and backend teams can work in parallel. Frontend teams can start building and testing against mock servers generated from the OpenAPI specification while the backend is being developed.
4. Documentation and Contract: The API specification serves as a contract and documentation from the beginning, ensuring consistency and clear expectations.

Example Workflow for API-First Development

1. Create the OpenAPI Specification: Define your API endpoints, request parameters, response structures, and other details in an OpenAPI document.
2. Generate Mock Servers and Client SDKs: Use tools like Swagger or Postman to generate mock servers and client SDKs to facilitate development and testing.
3. Develop the API: Implement the API based on the specification.
4. Validate Against the Specification: Ensure the API implementation adheres to the OpenAPI specification through automated tests and validation tools.

Code-First Development

In the code-first approach, the API code is written first, and the OpenAPI specification is generated afterwards. This approach is often used in existing projects or when developers prefer to prototype and iterate quickly without being constrained by a specification.

Example Workflow for Code-First Development

1. Develop the API: Write the API code and endpoints.
2. Generate the OpenAPI Specification: Use tools to generate the OpenAPI specification from the existing code. Many frameworks have plugins or libraries for this purpose (e.g., Springfox for Spring Boot, Swashbuckle for .NET).
3. Refine the Specification: Review and refine the generated specification to ensure it accurately reflects the API and includes necessary details like descriptions and examples.
4. Documentation and Validation: Use the specification to generate documentation and set up validation to ensure future changes adhere to the defined contract.

Choosing the Right Approach

• Greenfield Projects: For new projects, an API-first approach can provide a solid foundation and ensure a well-designed API from the start.
• Existing Projects: For existing projects, a code-first approach might be more practical, allowing you to generate and refine the specification based on the current implementation.

Tools for Both Approaches

• Swagger Editor: Create and edit OpenAPI specifications with real-time validation and visualization.
• Postman: Import OpenAPI specifications to create collections for testing and documentation.
• Swagger Codegen / OpenAPI Generator: Generate client SDKs, server stubs, and API documentation from OpenAPI specifications.
• Framework Integrations: Use libraries and plugins that integrate with your framework to generate and validate OpenAPI specifications (e.g., Springfox for Spring Boot, Swashbuckle for .NET).

Example

API-First Example:

1. Define OpenAPI Specification (openapi.yaml):

openapi: 3.0.0
info:
  title: Pet Store API
  description: API for managing a pet store
  version: 1.0.0
servers:
  - url: https://api.petstore.com/v1
paths:
  /pets:
    get:
      summary: List all pets
      responses:
        '200':
          description: A list of pets.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pet'
    post:
      summary: Create a pet
      requestBody:
        description: Pet to add to the store
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewPet'
      responses:
        '201':
          description: Pet created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
components:
  schemas:
    Pet:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        tag:
          type: string
    NewPet:
      type: object
      required:
        - name
      properties:
        name:
          type: string
        tag:
          type: string

2. Generate Mock Server: Use Swagger or Postman to generate a mock server for frontend development.

3. Develop API: Implement the API in your chosen framework, ensuring it matches the specification.

4. Validate API: Use automated tests to validate that the API conforms to the specification.

Code-First Example:

1. Develop API:

const express = require('express');
const app = express();
app.use(express.json());

let pets = [];
app.get('/pets', (req, res) => {
  res.json(pets);
});

app.post('/pets', (req, res) => {
  const pet = req.body;
  pets.push(pet);
  res.status(201).json(pet);
});

app.listen(3000, () => {
  console.log('Server is running on port 3000');
});

2. Generate OpenAPI Specification: Use a tool like swagger-jsdoc to generate the specification from comments or annotations in your code.

3. Refine Specification: Review and adjust the generated specification for accuracy and completeness.

4. Generate Documentation: Use the refined specification to generate API documentation.