Good API documentation improves developer experience. This guide covers creating comprehensive documentation with OpenAPI.
Basic OpenAPI Structure#
1openapi: 3.1.0
2info:
3 title: My API
4 version: 1.0.0
5
6paths:
7 /users:
8 get:
9 summary: List users
10 responses:
11 '200':
12 description: Success
13 content:
14 application/json:
15 schema:
16 type: array
17 items:
18 $ref: '#/components/schemas/User'
19
20components:
21 schemas:
22 User:
23 type: object
24 properties:
25 id:
26 type: string
27 name:
28 type: stringCode Generation#
# Generate TypeScript types
npx openapi-typescript openapi.yaml -o ./src/types/api.tsSwagger UI Integration#
import swaggerUi from 'swagger-ui-express';
import spec from './openapi.yaml';
app.use('/docs', swaggerUi.serve, swaggerUi.setup(spec));Write clear descriptions, provide examples, and keep documentation in sync with code.