Swagger/OpenAPI

Kodkod provides a built-in module to add Swagger/OpenAPI documentation to your backend. This allows you to visualize and interact with your API's resources without having any implementation logic in place.

Adding Swagger

To add Swagger to your project, run the following command in your terminal:

npx kodkod-stack@latest add swagger

This command will:

1. Detect your framework (Express, Hono, or Fastify).
2. Install the necessary dependencies.
3. Generate a configuration file in src/config/.

Framework Integration

After running the command, you need to add a few lines of code to your main entry point (src/index.ts) to enable the documentation.

import swaggerUi from 'swagger-ui-express';
import { swaggerSpec } from './config/swagger.config.js';

// ... after initializing app
app.use('/docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));

/**
 * @openapi
 * /health:
 *   get:
 *     description: Returns server status
 *     responses:
 *       200:
 *         description: OK
 */

import { setupSwagger } from './config/swagger.js';

// ... after initializing app
setupSwagger(app);

import { setupSwagger } from './config/swagger.js';

// ... after initializing fastify
await setupSwagger(fastify);

Viewing Documentation

Once integrated, start your development server:

npm run dev

Visit http://localhost:3000/docs (or your configured port) to view the interactive API documentation.