Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Browser & automation

api-docs

Workflow for creating comprehensive API documentation. Use when the user needs to document API endpoints.

girijashankarj · Static checks on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add girijashankarj/cursor-handbook --skill api-docs

About this skill


name: api-docs description: Workflow for creating comprehensive API documentation. Use when the user needs to document API endpoints.

Skill: Create API Documentation

Trigger

When the user needs to document API endpoints.

Prerequisites

  • API endpoints exist or are designed
  • OpenAPI/Swagger tooling available (optional)
  • Access to route definitions or handler files

Steps

Step 1: Inventory Endpoints

  • List all API endpoints
  • Group by resource/entity
  • Note HTTP method and path for each

Step 2: Document Each Endpoint

For each endpoint:

  • HTTP method and URL
  • Description and purpose
  • Authentication requirements
  • Request parameters (path, query, header)
  • Request body schema
  • Response schemas (success + errors)
  • Example request and response
  • Rate limiting details

Step 3: Create OpenAPI Spec

  • Define info, servers, security schemes
  • Create component schemas (reusable)
  • Define paths with all operations
  • Add examples for all schemas
  • Validate spec

Step 4: Generate Documentation

  • Use Swagger UI or Redoc for interactive docs
  • Host at /api/docs or similar
  • Include in CI/CD for auto-updates

Step 5: Review

  • All endpoints documented
  • Examples are accurate and working
  • Error responses documented
  • Authentication flow documented

Completion Checklist

  • All endpoints have method, URL, params, body, response
  • Error responses (4xx, 5xx) documented
  • Examples validated against live API or schema
  • OpenAPI spec validates (if used)

If Step Fails

  • Step 1 (inventory): Search for route definitions: **/*.route*.ts, **/routes/**, app.get|post|put|delete
  • Step 3 (OpenAPI): Use minimal spec first; add complexity incrementally. Validate with swagger-cli validate
  • Step 4 (generate): Swagger UI needs valid spec; Redoc is more forgiving. Check CORS if hosted separately

Example

Step 2 for POST /api/v1/orders: Method POST, URL /api/v1/orders, Body { customerId, items: [{ productId, quantity }] }, Response 201 { data: { id, status } }, Errors 400 validation, 404 customer not found.