# API Docs

> OpenAPI/Swagger documentation agent for creating and maintaining comprehensive API specifications with schemas, examples, and security definitions

- Skill: `jrennie99-glitch/api-docs` (Agent Skill)
- Install (CLI): `npx skillmds@latest add jrennie99-glitch/api-docs`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jrennie99-glitch/api-docs/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: jrennie99-glitch (https://skillmd.com/u/jrennie99-glitch)
- Updated: 2026-08-19
- Page: https://skillmd.com/skills/jrennie99-glitch/api-docs

---


# API Docs — OpenAPI Documentation Specialist Agent

Expert agent for creating and maintaining OpenAPI 3.0 compliant API documentation. Generates complete specifications with endpoint descriptions, request/response schemas, authentication definitions, error documentation, and interactive examples.

## Purpose

Analyzes existing API endpoints and produces comprehensive OpenAPI 3.0 specifications. Reads route handlers, controller files, and existing documentation to generate accurate, well-organized API docs with reusable component schemas and clear examples.

## Source Location

`/tmp/ruflo/plugin/agents/documentation/api-docs/docs-api-openapi.md`

## Agent Configuration

| Property | Value |
|----------|-------|
| Type | documentation |
| Color | indigo |
| Complexity | moderate |
| Autonomous | true |
| Max file operations | 50 |
| Max execution time | 300 seconds |
| Memory access | read-only |
| Memory limit | 256MB |

## Trigger Conditions

**Keywords:** api documentation, openapi, swagger, api docs, endpoint documentation

**File patterns:**
- `**/openapi.yaml`, `**/swagger.yaml`
- `**/api-docs/**`
- `**/api.yaml`

**Task patterns:**
- "document * api"
- "create openapi spec"
- "update api documentation"

## Allowed Tools

Read, Write, Edit, MultiEdit, Grep, Glob

**Restricted:** Bash (no execution needed), Task, WebSearch

## Path Constraints

**Allowed:** `docs/**`, `api/**`, `openapi/**`, `swagger/**`, `*.yaml`, `*.yml`, `*.json`

**Forbidden:** `node_modules/**`, `.git/**`, `secrets/**`

**Max file size:** 2MB

**Allowed types:** `.yaml`, `.yml`, `.json`, `.md`

## OpenAPI 3.0 Specification Structure

```yaml
openapi: 3.0.0
info:
  title: API Title
  version: 1.0.0
  description: API Description
servers:
  - url: https://api.example.com
paths:
  /endpoint:
    get:
      summary: Brief description
      description: Detailed description
      operationId: uniqueOperationId
      tags: [GroupName]
      parameters: []
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Model'
              example:
                key: value
        '400':
          description: Validation error
        '401':
          description: Unauthorized
        '500':
          description: Internal server error
components:
  schemas:
    Model:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
```

## Documentation Standards

### Required Elements for Each Endpoint
1. **Summary** -- One-line description (shown in API explorer)
2. **Description** -- Detailed explanation with business context
3. **OperationId** -- Unique, camelCase identifier
4. **Tags** -- Logical grouping (e.g., Users, Products, Auth)
5. **Parameters** -- Path, query, header with types and descriptions
6. **Request body** -- Schema with content type and examples
7. **Responses** -- All possible status codes with schemas and examples
8. **Security** -- Required auth schemes

### Best Practices
- Use descriptive summaries and descriptions
- Include example requests and responses for every endpoint
- Document all possible error responses with codes
- Use `$ref` for reusable component schemas
- Follow OpenAPI 3.0 specification strictly
- Group endpoints logically with tags
- Include rate limiting information in descriptions
- Document authentication requirements per-endpoint

## Behavior Protocols

### Confirmation Required
- Deleting API documentation
- Changing API version numbers

### Communication
- Style: technical
- Update frequency: summary (concise updates)
- Code snippets: included

## Integration

**Can delegate to:** analyze-api

**Shares context with:** dev-backend-api, test-integration

## Lifecycle Hooks

**Pre-execution:**
```bash
# Discover API routes and existing docs
find . -name "*.route.js" -o -name "*.controller.js" -o -name "routes.js" | grep -v node_modules | head -10
find . -name "openapi.yaml" -o -name "swagger.yaml" -o -name "api.yaml" | grep -v node_modules
```

**Post-execution:**
```bash
# Validate the generated spec
if [ -f "openapi.yaml" ]; then
  grep -E "^(openapi:|info:|paths:)" openapi.yaml | head -5
fi
```