api-doc-gen 1.0.0

Auto-generate OpenAPI 3.0 documentation from Python API source code

api-doc-gen

Auto-generate OpenAPI 3.0 documentation from Python API source code.

A CLI tool that scans Python source files (Flask, FastAPI, Django REST) for API route definitions and generates complete OpenAPI 3.0 specifications with documentation quality validation.

Features

• Multi-Framework Scanning — Detects Flask, FastAPI, and Django REST Framework routes
• OpenAPI 3.0 Generation — Produces valid OpenAPI specs in YAML or JSON
• Documentation Quality Validation — 10 built-in rules (DOC-001 to DOC-010)
• Coverage Analysis — Track documentation completeness by endpoint and method
• Rich Terminal Output — Color-coded tables with quality grades
• HTML Report Generation — Shareable documentation reports
• CI/CD Integration — --fail-on flag for pipeline gates

Installation

pip install -e .

Quick Start

# Generate demo project
api-doc-gen demo

# Scan for endpoints
api-doc-gen scan demo-api/

# Generate OpenAPI spec
api-doc-gen generate demo-api/ -o openapi.yaml

# Validate documentation quality
api-doc-gen validate demo-api/

# Check coverage
api-doc-gen coverage demo-api/

# Generate HTML report
api-doc-gen report demo-api/ -o docs.html

# List validation rules
api-doc-gen rules

Validation Rules

Rule	Severity	Description
DOC-001	ERROR	Endpoint missing summary
DOC-002	WARNING	Endpoint missing description
DOC-003	ERROR	No response definitions
DOC-004	WARNING	Parameter missing description
DOC-005	INFO	No tags assigned
DOC-006	WARNING	Missing operation ID
DOC-007	ERROR	POST/PUT/PATCH without request body
DOC-008	ERROR	Duplicate operation ID
DOC-009	ERROR	Path parameter not documented
DOC-010	WARNING	Inconsistent path naming (mixed case)

CI/CD Integration

- name: API Doc Validation
  run: |
    api-doc-gen validate src/ --fail-on error

Testing

python -m pytest tests/ -v

License

MIT