## Curation Note API documentation quality directly impacts developer adoption and support costs. This skill draws inspiration from industry-leading docs like Stripe, Twilio, and GitHub. The emphasis on runnable code examples addresses the primary developer need: "show me how to use this." The OpenAPI-first approach ensures documentation stays synchronized with implementation. ## Documentation Structure ### 1. Getting Started ````markdown ## Quick Start Get up and running in 5 minutes. ### 1. Get Your API Key Sign up at [dashboard.myapi.com](https://dashboard.myapi.com) and create an API key. ### 2. Install the SDK ```bash npm install @myapi/sdk ``` ```` ### 3. Make Your First Request ```javascript import { MyAPI } from '@myapi/sdk'; const api = new MyAPI('your-api-key'); const user = await api.users.create({ email: 'user@example.com', name: 'Jane Doe' }); console.log(user.id); // usr_1234567890 ``` That's it! You've created your first user. ```` ### 2. Authentication ```markdown ## Authentication All API requests require authentication via an API key. ### Using Your API Key Include your API key in the `Authorization` header: ```bash curl https://api.myapi.com/v1/users \ -H "Authorization: Bearer sk_live_abc123" ```` ### Environments | Environment | Base URL | Key Prefix | | ----------- | ------------------- | ---------- | | Production | `api.myapi.com` | `sk_live_` | | Sandbox | `sandbox.myapi.com` | `sk_test_` | ### Rate Limits - 100 requests per minute (free tier) - 1,000 requests per minute (pro tier) - Rate limit headers included in all responses ```http X-RateLimit-Limit: 100 X-RateLimit-Remaining: 95 X-RateLimit-Reset: 1609459200 ``` ```` ### 3. Endpoint Documentation ```markdown ## Create User Creates a new user in your account. `POST /v1/users` ### Request Body | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | email | string | Yes | User's email address | | name | string | No | User's full name | | metadata | object | No | Arbitrary key-value pairs | ### Example Request ```bash curl https://api.myapi.com/v1/users \ -H "Authorization: Bearer sk_live_abc123" \ -H "Content-Type: application/json" \ -d '{ "email": "user@example.com", "name": "Jane Doe", "metadata": { "role": "admin" } }' ```` ### Response ```json { "id": "usr_1234567890", "object": "user", "email": "user@example.com", "name": "Jane Doe", "created_at": "2026-01-14T12:00:00Z", "metadata": { "role": "admin" } } ``` ### Errors | Status | Code | Description | | ------ | --------------- | ------------------------ | | 400 | `invalid_email` | Email format is invalid | | 409 | `email_exists` | Email already registered | ```` ## OpenAPI Specification ```yaml openapi: 3.0.0 info: title: MyAPI version: 1.0.0 description: API for managing users and resources servers: - url: https://api.myapi.com/v1 description: Production - url: https://sandbox.myapi.com/v1 description: Sandbox security: - bearerAuth: [] paths: /users: post: summary: Create user operationId: createUser requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateUserRequest' responses: '201': description: User created content: application/json: schema: $ref: '#/components/schemas/User' components: securitySchemes: bearerAuth: type: http scheme: bearer schemas: User: type: object properties: id: type: string example: usr_1234567890 email: type: string format: email name: type: string ```` ## Best Practices 1. **Lead with examples** - Show before telling 2. **Runnable code** - Examples should work copy-paste 3. **Multiple languages** - Provide examples in popular SDKs 4. **Error documentation** - List all possible errors 5. **Version clearly** - Show API version in all examples 6. **Keep updated** - Automate from OpenAPI spec 7. **Include common scenarios** - Pagination, filtering, etc.