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.