Swagger & OpenAPI (OAS)

If your API isn't documented, it doesn't exist. OpenAPI is the world's most popular standard for defining RESTful interfaces.

1. Why document with OAS?

• Interactivity: Clients can test the API directly from the docs.
• Contract First: Design the API with the frontend team before coding.
• Auto-Generation: Generate client libraries in 20+ languages automatically.

2. Swagger UI Integration

In Node.js, swagger-jsdoc and swagger-ui-express are the standard choices.

const swaggerJsdoc = require('swagger-jsdoc');
const swaggerUi = require('swagger-ui-express');

const options = {
  definition: {
    openapi: '3.0.0',
    info: { title: 'My API', version: '1.0.0' },
  },
  apis: ['./routes/*.js'], // Path to the API docs
};

const specs = swaggerJsdoc(options);
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(specs));

3. Documenting a Route

Use YAML comments directly above your code to keep documentation and implementation together.

/**
 * @openapi
 * /users:
 *   get:
 *     description: Returns a list of users
 *     responses:
 *       200:
 *         description: Success
 */