api-documentation

Files (1)

• SKILL.md

SKILL.md (first lines)

# API Documentation Skill

Generate clear, complete, professional API documentation from any form of API input.

---

## Supported Input Formats

Accept any of the following as input:
- **OpenAPI / Swagger** (YAML or JSON, v2 or v3)
- **Endpoint list** (plain text, e.g. `GET /users/:id`)
- **Route definitions** (Express, FastAPI, Django, Rails, etc.)
- **Controller / handler code** (infer from function signatures and decorators)
- **Informal descriptions** ("I have an endpoint that creates a user and takes name + email")
- **Postman collections** (JSON)
- **gRPC proto files** (document as method-based API)
- **GraphQL schema** (document as query/mutation reference)

If the input is ambiguous, make reasonable inferences and note assumptions clearly.

---

## Output Structure

Produce documentation with these sections, omitting any that are not applicable:

### 1. Overview
- API name and short description
- Base URL (if known or inferable)
- Authentication method(s) (API key, Bearer token, OAuth2, etc.)
- Versioning scheme (if present)
- General conventions (date formats, pagination, error codes)

### 2. Authentication
- How to authenticate
- Token/key location (header, query param, cookie)
- Example header or request snippet
- Token expiry / refresh flow (if mentioned)

### 3. Endpoints (one section per endpoint)

For each endpoint, document:

```
### [METHOD] /path/to/endpoint
**Summary**: One-line description of what this endpoint does.

**Description**: (Optional) Longer explanation, use cases, side effects.

**Authentication**: Required / Optional / None

#### Path Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| id   | string | Yes    | Unique identifier of the resource |

#### Query Parameters
| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| page | integer | No  | 1       | Page number for pagination |

#### Request Body
Content-Type: application/json

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

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| field | string | Yes    | Description of field |

#### Responses

**200 OK**
\`\`\`json
{
  "id": "abc123",
  "name": "Example"
}
\`\`\`

**400 Bad Request** — Validation error
**401 Unauthorized** — Missing or invalid token
**404 Not Found** — Resource does not exist
**500 Internal Server Error** — Unexpected server error

#### Example Request
\`\`\`bash
curl -X POST https://api.example.com/v1/users \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice", "email": "alice@example.com"}'
\`\`\`

#### Example Response
\`\`\`json
{
  "id": "u_abc123",
  "name": "Alice",
  "email": "alice@example.com",
  "createdAt": "2026-03-20T10:00:00Z"
}
\`\`\`
```

### 4. Data Models / Schemas
- Document reusable objects (User, Order, Error, etc.)
- Include field name, type, required/optional, and description
- Use tables or JSON schema notation

### 5. Error Reference
Standard error format and all documented error codes, e.g.:

| Code | Meaning | Resolution |
|------|---------|------------|
| 400  | Bad Request | Check request body |

From LambdaTest/agent-skills, MIT.

More from LambdaTest/agent-skills