Api Documentation

---
name: api-documentation
description: "Technical documentation, API references, user guides, and docs-as-code workflows."
lastReviewed: 2026-04-30
---

# API Documentation Skill


> Technical documentation, API references, user guides, and docs-as-code workflows.

---

## Documentation Project Scaffolding

### Recommended Folder Structure

```text
docs-project/
├── .github/
│   ├── copilot-instructions.md    # Docs-specific the AI assistant context
│   └── prompts/
│       └── api-review.prompt.md
├── docs/
│   ├── index.md                   # Landing page / overview
│   ├── getting-started/
│   │   ├── installation.md
│   │   ├── quick-start.md
│   │   └── configuration.md
│   ├── guides/
│   │   ├── user-guide.md
│   │   └── admin-guide.md
│   ├── api/
│   │   ├── overview.md
│   │   ├── authentication.md
│   │   ├── endpoints/
│   │   │   └── [resource].md
│   │   └── errors.md
│   ├── reference/
│   │   ├── glossary.md
│   │   └── faq.md
│   └── contributing/
│       ├── style-guide.md
│       └── templates.md
├── examples/
│   ├── code-snippets/
│   └── sample-projects/
├── assets/
│   ├── images/
│   └── diagrams/
├── CHANGELOG.md
├── README.md
└── mkdocs.yml                     # Or docusaurus.config.js
```

### DOCS-PLAN.md Template

```markdown
# Documentation Plan: [Product/API Name]

## Scope
- **Product**: [What are we documenting?]
- **Audience**: [Developers / Admins / End Users]
- **Prerequisites**: [What readers should know]

## Documentation Types

| Type | Location | Status |
|------|----------|--------|
| Getting Started | docs/getting-started/ | ⬜ |
| User Guide | docs/guides/user-guide.md | ⬜ |
| API Reference | docs/api/ | ⬜ |
| Examples | examples/ | ⬜ |

## Style Guidelines
- **Tone**: [Technical but approachable]
- **Person**: [Second person - "you"]
- **Tense**: [Present tense]
- **Code style**: [Language-specific conventions]

## Quality Checklist
- [ ] All endpoints documented
- [ ] Code examples tested and working
- [ ] Screenshots current
- [ ] Links verified
- [ ] Spelling/grammar checked
```

### API-ENDPOINT.md Template

```markdown
# [Endpoint Name]

[One-line description of what this endpoint does]

## Request

\`\`\`http
[METHOD] /api/v1/[resource]
\`\`\`

### Headers

| Header | Required | Description |
|--------|----------|-------------|
| Authorization | Yes | Bearer token |
| Content-Type | Yes | application/json |

### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| id | string | Yes | Resource identifier |

### Request Body

\`\`\`json
{
  "field": "value"
}
\`\`\`

## Response

### Success (200 OK)

\`\`\`json
{
  "data": {
    "id": "123",
    "field": "value"
  }
}
\`\`\`

### Errors

| Code | Description |
|------|-------------|
| 400 | Invalid request body |
| 401 | Unauthorized |
| 404 | Resource not found |

## Example

\`\`\`bash
curl -X GET "https://api.example.com/v1/resource/123" \
  -H "Authorization: Bearer $TOKEN"
\`\`\`
```

### copilot-instructions.md Template (Documentation Projects)

```markdown
# [Product Name] Documentation — Context

## Project Overview
[What product/API this documents, current status]

## Current Phase
- [x] Structure defined
- [ ] Getting started complete
- [ ] API reference complete
- [ ] Examples tested

## Key Files
- Docs plan: DOCS-PLAN.md
- Style guide: docs/contributing/style-guide.md
- API overview: docs/api/overview.md

## the AI assistant Guidance
- **Audience**: [Developers with X experience level]
- **Tone**: Technical but approachable
- Use second person ("you") not third person
- Include working code examples for every endpoint
- Link to related endpoints/concepts

## Style Rules
- Headings: Sentence case
- Lists: No periods for fragments, periods for sentences
- Code: Include language identifier in fenced blocks
- Links: Use relative paths within docs/

## Don't
- Don't assume reader knows internal terminology
- Don't document deprecated features without clear warnings
- Don't include placeholder examples — all code must work
```

### Documentation Project Audit Checklist

```markdown
## Documentation Project Audit

### Structure Assessment
- [ ] Clear navigation hierarchy
- [ ] Getting started section exists
- [ ] API reference organized by resource
- [ ] Examples directory with working code

### the AI assistant-Readiness Assessment
- [ ] copilot-instructions.md exists
- [ ] Audience clearly defined
- [ ] Style guide documented
- [ ] Key files linked

### Content Assessment
- [ ] All public endpoints documented
- [ ] Authentication explained
- [ ] Error codes listed
- [ ] Code examples in multiple languages (if applicable)

### Quality Assessment
- [ ] All links valid
- [ ] Code examples tested
- [ ] Screenshots current
- [ ] Consistent formatting
```

---

## Documentation Types

### API Reference Structure

| Section | Purpose |
|---------|---------|
| **Overview** | What the API does, base URL, versioning |
| **Authentication** | How to get and use credentials |
| **Rate Limits** | Throttling rules and headers |
| **Endpoints** | Per-endpoint details |
| **Errors** | Error format and common codes |
| **Changelog** | API version history |

### User Guide Structure

| Section | Purpose |
|---------|---------|
| **Introduction** | What, why, for whom |
| **Installation** | How to set up |
| **Quick Start** | First success in 5 minutes |
| **Core Concepts** | Key ideas to understand |
| **How-To Guides** | Task-oriented walkthroughs |
| **Troubleshooting** | Common issues and fixes |

### README Best Practices

| Section | Required? |
|---------|-----------|
| Project name + description | ✅ Yes |
| Badges (build, version) | Recommended |
| Quick start / Installation | ✅ Yes |
| Usage examples | ✅ Yes |
| Configuration | If applicable |
| Contributing | Recommended |
| License | ✅ Yes |

---

## Docs-as-Code Tools

### Static Site Generators

| Tool | Best For | Config File |
|------|----------|-------------|
| **MkDocs** | Python projects, simple setup | mkdocs.yml |
| **Docusaurus** | React, versioning, i18n | docusaurus.config.js |
| **Sphinx** | Python autodocs | conf.py |
| **GitBook** | Beautiful docs, non-technical | book.json |
| **VitePress** | Vue projects, fast | .vitepress/config.js |

### API Documentation Tools

| Tool | Format | Output |
|------|--------|--------|
| **OpenAPI/Swagger** | YAML/JSON spec | Interactive docs |
| **Redoc** | OpenAPI | Static HTML |
| **Stoplight** | Design-first | Portal |
| **Postman** | Collections | Shareable docs |

---

## Writing Patterns

### The 4 Cs of Technical Writing

| Principle | Meaning |
|-----------|---------|
| **Clear** | No ambiguity, simple words |
| **Concise** | No filler, respect reader's time |
| **Correct** | Accurate, tested, up-to-date |
| **Complete** | All needed info present |

### Code Example Guidelines

| Do | Don't |
|----|-------|
| Show complete, runnable examples | Partial snippets without context |
| Include error handling | Happy path only |
| Use realistic data | `foo`, `bar`, `test123` |
| Explain non-obvious parts | Assume reader knows everything |

### Common Pitfalls

| Pitfall | Solution |
|---------|----------|
| Outdated screenshots | Automate with Puppeteer/Playwright |
| Broken links | CI link checking |
| Stale examples | Tests for code samples |
| Jargon overload | Glossary + define on first use |

---