SKILL DOCUMENTATION

Bruno API Documentation Generator

Generate comprehensive API docs from Bruno (.bru) files by mapping requests to a Django implementation (DRF/Django Ninja), including auth, multi-tenant filtering, schemas, and code references.

Overview

Generate comprehensive API docs from Bruno (.bru) files by mapping requests to a Django implementation (DRF/Django Ninja), including auth, multi-tenant filtering, schemas, and code references.

This skill ships inside the Bruno API Docs plugin and can be installed through the Claude Code marketplace or directly in Codex from its skill path.

Parent Surface

Parent docs: Bruno API Docs

Related wrapper commands from the parent plugin:

/bruno-api:docs

Inputs & Modes

This Skill expects one of:

Optional flags:

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

  • A path to a single Bruno file (usually *.bru), OR
  • --scan to analyze all .bru files under a directory.
  • --dry-run – produce an analysis plan only (no deep codebase search).
  • --output – write the generated markdown documentation to a file.
  • 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

Return a short plan containing:

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

Use severity tags only when something prevents correctness/completeness:

  • 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”).
  • #
  • ` `
  • 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)
  • [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

For each .bru file:

Treat these repo conventions as first-class when present:

Once the route is found, identify the implementation type:

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

For the located endpoint:

Write the markdown doc per “Full documentation output”.

Rules:

include a representative sample, not the entire universe of fields.

(ty first when configured, else pyright, else mypy) and avoid recommending blanket suppressions.

  • 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.
  • 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.
  • 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.
  • 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.
  • 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.
  • If you recommend follow-up code changes, mention the repo's active type gate (ty first when configured, else pyright, else mypy) and avoid recommending blanket suppressions.
  • When you’re unsure, be explicit about assumptions and mark with [SHOULD_FIX].
  • If --scan :
  • 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 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.

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

  • 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.

Resources

Declared allowed tools:

BashReadEditGlobGrep

Installation

Switch between Claude Code and Codex, then copy the install command for the runtime you use.

claude plugin marketplace add DiversioTeam/agent-skills-marketplace
claude plugin install bruno-api@diversiotech

Invocation:

/bruno-api:docs