Great API documentation reduces support burden and increases adoption. Here's how to create docs that developers actually want to read.
Documentation Structure#
Essential Sections#
Loading code block...
OpenAPI Specification#
Complete Example#
Loading code block...
Code Examples#
Multiple Languages#
Loading code block...
const product = await response.json();
</tab>
<tab title="Python">
```python
import requests
response = requests.post(
'https://api.example.com/v1/products',
headers={'Authorization': f'Bearer {api_key}'},
json={
'name': 'Widget',
'price': 29.99,
'category': 'electronics',
}
)
product = response.json()
Error Documentation#
Loading code block...
Handling Errors#
Loading code block...
## Interactive Documentation
### Swagger UI / Redoc
```typescript
// Express setup for Swagger UI
import swaggerUi from 'swagger-ui-express';
import YAML from 'yamljs';
const swaggerDoc = YAML.load('./openapi.yaml');
app.use('/docs', swaggerUi.serve, swaggerUi.setup(swaggerDoc, {
customSiteTitle: 'My API Docs',
customCss: '.swagger-ui .topbar { display: none }',
}));
// Redoc alternative
app.get('/docs', (req, res) => {
res.send(`
<!DOCTYPE html>
<html>
<head>
<title>API Documentation</title>
<link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
<style>body { margin: 0; padding: 0; }</style>
</head>
<body>
<redoc spec-url='/openapi.yaml'></redoc>
<script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"></script>
</body>
</html>
`);
});
Best Practices#
Loading code block...
Conclusion#
Great API documentation is an investment that pays off in developer adoption and reduced support burden. Start with OpenAPI, add code examples in multiple languages, and keep everything up to date.
Remember: developers judge your API by its documentation. Make it excellent.