Bruno API Documentation Generator Skill

Inputs & Modes

This Skill expects one of:

• •A path to a single Bruno file (usually *.bru), OR
• •--scan <dir> to analyze all .bru files under a directory.

Optional flags:

• •--dry-run – produce an analysis plan only (no deep codebase search).
• •--output <path> – write the generated markdown documentation to a file.

If inputs are missing or ambiguous, ask the user to confirm:

• •Which .bru file(s) to analyze.
• •Whether they want --dry-run or full documentation.
• •Whether an output file should be written.

Output Shape & Severity Tags

Dry-run output

Return a short plan containing:

• •Endpoint summary: method, URL, auth, and any detected params/body.
• •Where you will look in the Django codebase (specific file paths/directories).
• •Which documentation sections will be generated.
• •Complexity notes (e.g., “DRF ViewSet + serializer” vs “Ninja router + schema”).

Full documentation output

Generate a single markdown document for each endpoint using this structure:

• •# <Endpoint Name>
• •<METHOD> <URL Pattern>
• •Authentication, Permissions, Multi-tenant
• •## Overview
• •## Request (headers + params/body with types/validation)
• •## Response (success example + common error cases)
• •## Implementation Details (URL config + view + serializer/schema; always with file.py:line)
• •## Business Logic (step-by-step, include side effects like tasks/external calls)
• •## Frontend Integration (TypeScript types + call example + React Query hook example)
• •## Testing (Bruno tests + edge cases + required fixtures/data)
• •## Notes (perf considerations, related endpoints, rollout notes)

Use severity tags only when something prevents correctness/completeness:

• •[BLOCKING] – cannot locate the endpoint implementation or critical auth/permission logic.
• •[SHOULD_FIX] – documentation gaps due to missing/incomplete source details (e.g., response shape unclear).
• •[NOTE] – optional improvements, related endpoints, refactors, or performance observations.

Workflow

Step 1 — Parse the Bruno file(s)

For each .bru file:

• •Extract:
  • •HTTP method
  • •URL / path pattern
  • •Headers
  • •Query parameters
  • •Path parameters (from the URL pattern)
  • •Request body (and infer a schema where possible)
• •Detect authentication intent:
  • •JWT / token headers
  • •Session/cookie usage
  • •Explicit “no auth” signals
• •Capture any Bruno test/assert blocks as testing hints.

Step 2 — Locate the Django route & implementation

Treat these repo conventions as first-class when present:

• •If the URL starts with /api/v2/:
  • •Check dashboardapp/v2_urls.py.
  • •Check dashboardapp/views/v2/ for the view/viewset.
• •If the URL starts with /api/v2/pulse/:
  • •Check pulse_iq/api/ for Django Ninja routers/endpoints.
• •Otherwise:
  • •Search app-level urls.py modules for the path prefix.
  • •If needed, Grep for a distinctive path segment from the Bruno URL.

Once the route is found, identify the implementation type:

• •DRF
  • •View / ViewSet class and handler method (list, retrieve, create, custom actions).
  • •Serializer(s) used (including nested serializers) and validation rules.
  • •Permissions / authentication classes.
  • •Queryset and filtering (especially company/org scoping).
• •Ninja
  • •Router and endpoint function.
  • •Pydantic schema(s) and validation.
  • •Auth configuration/decorators.
  • •Multi-tenant scoping and access control.

Always record code references with line numbers (path/to/file.py:123).

Step 3 — Extract behavior and contracts

For the located endpoint:

• •Summarize the business purpose and any key invariants.
• •Document validation and error behavior:
  • •Common 400 reasons (schema/serializer validation).
  • •Auth failures (401) and permission failures (403).
  • •Not-found cases (404) and domain-specific error cases.
• •Identify multi-tenant constraints:
  • •How company/org is inferred (JWT claims, request context, URL param).
  • •Which queryset filters enforce scoping.
• •Note side effects:
  • •Background tasks (Celery), emails, webhooks, external service calls.
  • •Writes to critical models and any transactional boundaries.

Step 4 — Generate documentation

Write the markdown doc per “Full documentation output”.

Rules:

• •Prefer precise types over “string/number” when you can infer them.
• •Include at least one realistic example request and success response.
• •If response shape is dynamic or large, document the stable contract and include a representative sample, not the entire universe of fields.
• •When you’re unsure, be explicit about assumptions and mark with [SHOULD_FIX].

Step 5 — Handle --output and --scan

• •If --scan <dir>:
  • •Find all .bru files recursively under that directory.
  • •Generate one markdown doc per file.
  • •If no --output is provided, return docs in the response (grouped by file).
• •If --output <path> is provided:
  • •Write output to that path.
  • •If scanning multiple files, either:
    • •Write a single combined doc (with a clear table of contents), OR
    • •Write multiple files under an output directory (ask the user which they want).

Compatibility Notes

This Skill is designed to work with both Claude Code and OpenAI Codex.

• •Claude Code: install the corresponding plugin and use its slash commands (see plugins/bruno-api/commands/).
• •Codex: install the Skill directory and invoke name: bruno-api.

For installation, see this repo's README.md.