A service that analyzes OpenAPI specifications and generates natural language summaries and documentation using AI.

• Upload and parse OpenAPI specifications (JSON/YAML)
• Generate natural language summaries of API endpoints
• Asynchronous processing with job status tracking
• Structured logging and error handling
• Simple web interface for file uploads and results access

• Export summaries in multiple formats (Markdown, HTML, DOCX)
• Ad-hoc user queries
• Ask the tool to test endpoints for you

api_introspection/
├── src/
│   ├── api/
│   │   ├── routes.py          # FastAPI route definitions
│   │   └── models.py          # Request/response Pydantic models
│   ├── core/
│   │   ├── config.py          # Environment and app configuration
│   │   ├── storage.py         # Job data storage management
│   │   └── logging/           # Logging package
│   │       ├── __init__.py    # Package exports
│   │       ├── config.py      # Logging configuration
│   │       ├── core.py        # Core logging functionality
│   │       └── handlers.py    # Custom logging handlers
│   ├── services/
│   │   └── openai.py          # OpenAI API integration
│   └── tasks/
│       └── tasks.py           # Celery task definitions
├── web/
│   └── index.html            # Simple web interface for file uploads
├── tests/
│   ├── test_routes.py         # API endpoint tests
│   └── conftest.py            # pytest fixtures and configuration
├── celery_worker.py           # Celery worker configuration
├── pyproject.toml            # Project dependencies and tools config
└── DEBUGGING.md              # Development and debugging guide

The service provides a simple web interface for file uploads and results access:

1. Open your browser and navigate to http://localhost:8080
2. Use the file upload form to submit your OpenAPI specification
3. Wait for the analysis to complete
4. Download the results in your preferred format (Markdown or HTML)

For programmatic access, you can use the following API endpoints:

GET /api/health

Response:

{
    "status": "healthy"
}

POST /api/spec/upload

Request:

Supported Content Types:

• application/json
• text/yaml
• application/x-yaml
• text/plain
• text/x-yaml

Response:

{
    "job_id": "string"  // UUID for tracking the analysis job
}

Error Responses:

• 400: Invalid file type or no file provided
• 500: Server error during file processing

GET /api/spec/{job_id}/summary

Parameters:

Response States:

1. Processing:

{
    "detail": "Job is still processing"
}

Status Code: 202 Accepted

2. Completed:

{
    "status": "SUCCESS",
    "result": {
        // Summary content structure
        "endpoints": [...],
        "schemas": [...],
        "overview": "string"
    }
}

Status Code: 200 OK

3. Failed:

{
    "detail": "Job failed"
}

Status Code: 500 Internal Server Error

GET /api/spec/{job_id}/export

Parameters:

Response:

• Format: Markdown (default)
  • Content-Type: text/markdown
  • Filename: api-summary-{job_id}.md
• Format: HTML
  • Content-Type: text/html
  • Direct HTML content
• Format: DOCX
  • Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document
  • Filename: api-summary-{job_id}.docx

Error Responses:

• 404: Job not found
• 400: Unsupported file format
• 500: Export generation error

1. Clone the repository
2. Install dependencies:

poetry install

3. Create .env file with required variables:

OPENAI_API_KEY=your_api_key
ENV=development
LOG_LEVEL=DEBUG
REDIS_URL=redis://localhost:6379

4. Start Redis:

docker run -d -p 6379:6379 redis

5. Start Celery worker:

poetry run celery -A celery_worker worker --loglevel=info

6. Start the API server:

poetry run uvicorn src.main:app --reload

The project includes a Makefile with several useful commands to help with development:

make pc           # Run all code quality checks (ruff, mypy, pre-commit)
make fix         # Run pre-commit hooks to fix code style issues

make run         # Start the FastAPI development server with hot reload
make celery      # Start the Celery worker
make redis       # Start Redis server in daemon mode
make dev         # Start complete development environment (API + Celery + Redis)

make clean       # Stop all development processes (API, Celery, Redis)

Run the test suite:

poetry run pytest

With coverage:

poetry run pytest --cov=src

I created this repo for the following purposes:

• Get familiar with LLM tools I haven't used at all or only used to a limited extent.

• Create a production-grade mini project with robust infrastructure: CI/CD, lint, tests, documentation. I might later turn it into a template for future projects, extend the functionality, etc.