Api docs

Skill iamvirul/api-docs-skill/skills/api-docs

Claude Code plugin to generate OpenAPI 3.1 specs and documentation from code

Install

npx -y skills add iamvirul/api-docs-skill --skill api-docs

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

0 stars0 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Generate OpenAPI 3.1 specs and documentation from code. Supports Express, FastAPI, Flask, NestJS, Spring Boot, Gin, Rails, and more. Use when documenting APIs, creating OpenAPI specs, or generating API reference docs.

SKILL.md

4.8 KB, as published. Nobody here has run it

API Documentation Generator

Generate production-ready OpenAPI 3.1 specifications and documentation from your codebase.

Workflow

Phase 1: Discovery

Detect framework by scanning for:
- package.json → Express, NestJS, Fastify, Hono
- requirements.txt / pyproject.toml → FastAPI, Flask, Django REST
- go.mod → Gin, Echo, Chi, Fiber
- Gemfile → Rails API
- pom.xml / build.gradle → Spring Boot
- Cargo.toml → Axum, Actix-web

Find API entry points:

# Common patterns to search
app.get|post|put|patch|delete  # Express/Fastify
@app.route|@router             # Flask/FastAPI
@GetMapping|@PostMapping       # Spring
router.GET|POST                # Gin/Echo
resources|get|post             # Rails
@Controller|@Get|@Post         # NestJS

Extract endpoint metadata:
- HTTP method and path
- Path parameters (:id, {id}, <id>)
- Query parameters
- Request body schema
- Response schemas and status codes
- Authentication requirements
- Middleware/decorators

Phase 2: Schema Extraction

Type definitions → OpenAPI components/schemas:
- TypeScript interfaces/types
- Python Pydantic models, dataclasses, TypedDict
- Go structs with json tags
- Java/Kotlin DTOs
- Ruby serializers
Validation rules → OpenAPI constraints:
- Required fields
- Min/max values
- String patterns (email, uuid, etc.)
- Enums
- Array constraints
Existing documentation:
- JSDoc/TSDoc comments
- Python docstrings
- Go doc comments
- Swagger/OpenAPI annotations
- README files

Phase 3: OpenAPI Generation

Generate openapi.yaml with:

openapi: 3.1.0
info:
  title: <extracted from package.json/pyproject.toml or ask>
  version: <from version file or git tag>
  description: <from README or generate>
servers:
  - url: <detect from env/config or use placeholder>
paths:
  /endpoint:
    get:
      summary: <from docstring or generate>
      description: <detailed description>
      operationId: <function name>
      tags: [<from route grouping>]
      parameters: [<extracted>]
      requestBody: <if applicable>
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseType'
              example: <generate realistic example>
        '400': <validation errors>
        '401': <if auth required>
        '404': <if path params>
        '500': <server error>
      security: [<detected auth>]
components:
  schemas: <all extracted types>
  securitySchemes: <detected auth methods>

Phase 4: Documentation Output

Based on $ARGUMENTS or default to all:

OpenAPI Spec (openapi.yaml):
- Valid OpenAPI 3.1
- Realistic examples for all schemas
- Comprehensive error responses
Markdown (API.md):
- Table of contents
- Authentication section
- Endpoint reference with examples
- Schema definitions
- Error codes
Postman Collection (postman.json):
- Importable collection
- Environment variables
- Pre-configured requests

Phase 5: Validation

Before finalizing, validate:

Spec validity:
```
npx @redocly/cli lint openapi.yaml
```
Or if not available, validate structure manually.
Coverage check: List any endpoints found but not documented
Quality checks:
- All endpoints have descriptions
- All parameters documented
- Response examples provided
- Auth requirements specified

Framework-Specific Patterns

See reference.md for detailed extraction patterns per framework.

Output Format Selection

Argument	Output
`openapi`	OpenAPI 3.1 YAML only
`markdown`	API.md documentation
`postman`	Postman collection JSON
`all` (default)	All formats
`html`	Redoc-ready HTML

Example Usage

/api-docs                    # Auto-detect, generate all formats
/api-docs fastapi openapi    # FastAPI project, OpenAPI only
/api-docs express markdown   # Express project, Markdown only

Quality Standards

Generated documentation MUST include:

All public endpoints documented
Request/response examples for each endpoint
Authentication requirements clearly stated
Error responses documented (4xx, 5xx)
Parameter constraints (required, types, validation)
Consistent naming and formatting