Metadata-Version: 2.4
Name: api-doc-gen
Version: 1.0.0
Summary: Auto-generate OpenAPI 3.0 documentation from Python API source code
License: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: pyyaml>=6.0
Dynamic: license-file

# 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

```bash
pip install -e .
```

## Quick Start

```bash
# 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

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

## Testing

```bash
python -m pytest tests/ -v
```

## License

MIT
