api-documentation

Files (6)

• SKILL.md
• collection.bru · templates/bruno/
• Local.bru · templates/bruno/environments/
• folder.bru · templates/bruno/
• request.bru · templates/bruno/
• redocly.yaml · templates/

SKILL.md (first lines)

# API Documentation

## When to Apply

Activate this skill when:

- Creating or editing OpenAPI spec files in `docs/api/`
- Setting up the Redocly toolchain for the first time
- Linting or validating an OpenAPI description
- Bundling an OpenAPI spec for distribution or rendering
- Generating standalone HTML API documentation
- Adding Bruno requests, folders, or environments in `docs/bruno/`

---

## Toolchain Setup

Run this setup when `@redocly/cli` is not present inside `package.json`.

### 1. Install packages

Install the current release as a dev dependency — let npm resolve the version instead of hand-writing one into `package.json`:

```bash
npm install --save-dev @redocly/cli
```

Respect the project's existing setup:

- If a `yarn.lock`, `pnpm-lock.yaml`, or `bun.lockb` is present, use that package manager's equivalent instead of npm.
- Leave `.npmrc` (registries, scopes, auth) untouched and never delete or regenerate the lockfile.
- Commit the resulting `package.json` and lockfile changes together.

Then add to the `scripts` block in `package.json`:

```json
"lint:api-docs": "redocly lint",
"build:api-docs": "redocly bundle",
"preview:api-docs": "redocly build-docs docs/api/spec.yaml --output public/docs/api/index.html"
```

### 2. Create `redocly.yaml`

Read `.claude/skills/api-documentation/templates/redocly.yaml` and copy it to the project root. No changes needed to start — the template includes sensible defaults.

**Key `redocly.yaml` sections:**

| Section | Purpose |
|---|---|
| `apis` | Named API aliases — lets you run `redocly lint main` instead of specifying the path |
| `extends` | Base ruleset: `minimal`, `recommended`, `recommended-strict`, or `spec` |
| `rules` | Override individual rule severities (`error`, `warn`, `off`) |
| `resolve` | Configure HTTP headers for private `$ref` URLs |

### 3. Directory structure

```
docs/
└── api/
    ├── spec.yaml              # Root spec — info, servers, tags, paths (inline), components
    └── schemas/               # Reusable JSON schemas, referenced via $ref from spec.yaml
        ├── error.json
        ├── meta.json
        ├── links.json
        ├── {resource}-index.json
        ├── {resource}-show.json
        ├── {resource}-request.json
        └── ...
```

Paths are defined inline in `spec.yaml`. Only request/response body schemas live in separate files under `schemas/` as JSON. Reference them with relative paths:

```yaml
$ref: "schemas/{resource}-index.json"
```

---

## Linting

Always lint before bundling to catch issues early.

```bash
# Lint all configured APIs (uses redocly.yaml)
redocly lint

# Lint a specific API alias
redocly lint main

# Lint with a specific ruleset (overrides redocly.yaml extends)
redocly lint --extends=recommended-strict

# Output formats for CI integration
redocly lint --format=github-actions
redocly lint --format=json

# Generate an ignore file to suppress known issues
redocly lint --generate-ignore-file
```

### Rulesets

| Ruleset | Use when |
|---|---|
| `minimal` | Existing APIs with lots of legacy issues — few error-level rules |
| `recommended` | Greenfield APIs — good balance of strictness |
| `recommended-strict` | All warnings become errors — use in CI for enforcement |
| `spec` | Pure OpenAPI spec compliance only |

### Useful lint rules to enforce

```yaml
rules:
  operation-operationId: error       # Every operation must have a unique ID
  operation-summary: error           # Every operation must have a summary
  no-unused-components: error        # No dead components in the spec
  paths-kebab-case: warn             # /kebab-case paths
  tag-description: warn              # Tags must have descriptions
  no-ambiguous-paths: error          # Catch path conflicts early

From mindtwo/agent-tooling, MIT.

More from mindtwo/agent-tooling