# API Doc Writing

> Write clear and consistent API documentation following team standards. Use when creating or editing REST API reference docs.

- Skill: `datawhalechina/api-doc-writing` (Agent Skill)
- Install (CLI): `npx skillmds@latest add datawhalechina/api-doc-writing`
- Raw SKILL.md: https://api.skillmd.com/api/skills/datawhalechina/api-doc-writing/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- License: MIT
- Author: datawhalechina (https://skillmd.com/u/datawhalechina)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/datawhalechina/api-doc-writing

---


# API Documentation Writing Skill

Guidelines for writing REST API reference documentation.

## When to use

Use this skill when:

- Writing new API endpoint documentation
- Editing existing API reference pages
- Reviewing API docs for consistency

## Document structure

### Standard sections

1. **Overview** - Brief description of the endpoint purpose
2. **Request** - HTTP method, URL, headers, and body parameters
3. **Response** - Status codes and response body schema
4. **Examples** - Request/response examples with curl commands
5. **Errors** - Common error codes and troubleshooting

## Formatting rules

### Endpoint naming

- Use lowercase with hyphens for URL paths
- Use nouns for resources, not verbs
- Version prefix required: `/v1/users`, not `/users`

### Parameter tables

- Every parameter must have: name, type, required, description
- Use `string`, `integer`, `boolean`, `array`, `object` for types
- Mark optional parameters explicitly

### Examples section

- Include at least one success and one error example
- Use curl commands for request examples
- Show full JSON response bodies

## Best practices

- Start each endpoint doc with a one-sentence summary
- Document rate limits and authentication requirements upfront
- Keep examples realistic but anonymized (no real API keys)
- Link to related endpoints for discoverability

## Example

Request:

```bash
curl -X GET "https://api.example.com/v1/users/123" \
  -H "Authorization: Bearer <token>"
```

Response:

```json
{
  "id": 123,
  "name": "Alice",
  "email": "alice@example.com"
}
```