documenting-apis

Generate API specification documentation from codebase analysis. Detects REST endpoints, function signatures, type definitions, and schemas. Triggers: API specification, endpoints, REST API, type definitions, OpenAPI, Swagger, API documentation.

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026⬇️2downloads

When & Why to Use This Skill

This Claude skill automates the generation of comprehensive API specification documentation by performing deep codebase analysis. It intelligently detects REST endpoints, function signatures, and data schemas across various frameworks like Express, FastAPI, and Next.js, ensuring your OpenAPI or Swagger documentation remains synchronized with your actual implementation.

Use Cases

  • Legacy Project Documentation: Automatically generate a complete API specification for existing codebases that lack formal documentation, saving hours of manual reverse-engineering.
  • Continuous Documentation Updates: Keep API docs in sync with rapid code changes by re-running the analysis to detect new endpoints or modified request/response schemas during the development cycle.
  • Cross-Framework Analysis: Standardize documentation across polyglot microservices by extracting endpoint data from diverse environments including Node.js (Express/Next.js), Python (FastAPI/Flask), and Django.
  • Type-Safe Schema Extraction: Extract detailed data models from TypeScript interfaces, Zod schemas, or Pydantic classes to provide developers with accurate request and response body definitions.
namedocumenting-apis
description>
TriggersAPI specification, endpoints, REST API, type definitions,
allowed-toolsRead, Write, Grep, Glob, Bash, Task

docs:api - API Specification Generation

Auto-generate API documentation from codebase analysis.

Detection Items

Category Targets
REST Endpoints Express, Fastify, Hono, Next.js, Flask, FastAPI, Django REST
Functions tree-sitter extraction, TypeScript types, JSDoc, docstrings
Types interface, type, Zod, Yup, dataclass, Pydantic
OpenAPI openapi.yaml/json, swagger.yaml/json

Framework Detection Patterns

Framework Pattern
Express/Fastify/Hono app.get(), router.post()
Next.js app/api/**/route.ts, pages/api/**/*.ts
Flask @app.route()
FastAPI @app.get(), @app.post()
Django REST @api_view

Analysis Scripts

Script Purpose
scripts/detect-endpoints.sh HTTP method, path, handler, file location
scripts/extract-types.sh Type name, fields, related types

Generated Structure

# API Specification

## Endpoint List
### GET /api/users
**Request**: params table
**Response**: JSON example

## Type Definitions
### User
| Field | Type | Description |

Usage

/docs:api                    # Generate API docs
"Generate API specification" # Natural language

Markdown Validation

After generation, validate output with:

~/.claude/skills/scripts/validate-markdown.sh {output-file}

Non-blocking (warnings only) - style issues don't block document creation.

References

  • Related: documenting-architecture, setting-up-docs, documenting-domains