bruno-api

name	bruno-api
description	Generate comprehensive API endpoint documentation from Bruno (.bru) files by mapping requests to a Django4Lyfe/Diversio-style backend implementation (Django REST Framework or Django Ninja), including auth/permissions, multi-tenant filtering, request/response schemas, and line-numbered code references. Use for single endpoints, directory scans of .bru files, or when writing docs to a specific output path.
allowed-tools	["Bash","Read","Edit","Glob","Grep"]

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.

For Codex users:

• Install via skill-installer with --repo DiversioTeam/agent-skills-marketplace --path plugins/bruno-api/skills/bruno-api.
• Use $skill bruno-api to invoke.

For Claude Code users:

• Install via /plugin install bruno-api@diversiotech.
• Use /bruno-api:docs to invoke.