DEV Community: Mr Fatalyst

FastOpenAPI: A Reason to Believe in Open Source Community

Mr Fatalyst — Fri, 18 Apr 2025 14:07:35 +0000

Links

Documentation: Docs
Repository: GitHub
PyPi: FastOpenAPI

About a month ago, I decided to share my project, FastOpenAPI, with the Hacker News community. FastOpenAPI is a library designed to simplify working with OpenAPI schemas and integrating them with various Python frameworks. My goal was to create a user-friendly solution, inspired by FastAPI, for developers using Falcon, AioHTTP, Tornado, and other popular frameworks.

Why did I create FastOpenAPI?

If you've ever had to maintain API documentation for multiple Python frameworks simultaneously, you know how cumbersome it can be. Each framework often requires a unique approach. Appreciating FastAPI’s simplicity and intuitive design, I wanted to bring that same convenience and efficiency to other platforms.

How does FastOpenAPI work?

FastOpenAPI acts as a universal layer providing consistent creation and validation of OpenAPI schemas across multiple frameworks. It implements a unified interface alongside tools to streamline integration, documentation, and data validation.

Request processing flow in FastOpenAPI:

Receiving Request

The client sends an HTTP request to a specific route.
The web framework (Flask, Falcon, AioHTTP, Starlette, Sanic, Quart, Tornado) receives the request.

Forwarding Request

The framework delegates the request to the handler registered by FastOpenAPI.
The router extracts URL path parameters, query parameters, and the request body (JSON).

Validating Data

The router analyzes the signature of the user-defined function.
Input data is transformed based on type annotations.
Pydantic models (if used) are validated.

Calling User Function

The router passes validated arguments to the user-defined function, supporting synchronous and asynchronous operations.

Handling Result

The function returns a result.
The router serializes the result, especially for Pydantic models, and adds metadata like HTTP status codes.

Forming Response

The router converts the serialized result into a format compatible with the specific framework.
The framework sends back an HTTP response.

Handling Errors

Any exceptions are caught by the router.
Errors are standardized into a JSON response with an appropriate HTTP status code.

This architecture provides:

Consistent route definitions across frameworks.
Automatic validation and transformation of data.
Standardized error handling.
Automatic OpenAPI documentation generation.

The core of FastOpenAPI allows developers to concentrate on business logic instead of worrying about integration specifics.

Community Feedback and Improvements

I shared FastOpenAPI on Hacker News to get constructive criticism and recommendations, a platform known for its candid and professional audience.

My post received a very positive response: it remained on the front page for over 12 hours, garnered approximately 150 upvotes, and sparked valuable discussions. The community suggested essential improvements, such as:

Class-level schema caching for better performance.
Standardized error handling.
Support for basic Python data types as response models.

Version 0.5.0 – A Major Milestone

Thanks to community feedback, version 0.5.0 featured highly anticipated enhancements:

Integration with AioHTTP.
Implementation of class-level schema caching.
Improved error handling mechanisms.
Support for simple data types as response models.
Comprehensive documentation overhaul (fastopenapi.fatalyst.dev).

A significant pull request also ensured consistent use of aliases from Pydantic during serialization and schema generation.

The community response surpassed my expectations, providing actionable suggestions and motivating further project development.

What's next?

Future releases will focus on simplifying the API, removing deprecated solutions, enhancing performance, and expanding framework support. Continuous documentation improvements and more usage examples will remain a priority.

Acknowledgments

I'm incredibly grateful to everyone who participated in discussions on Hacker News and other platforms. Your valuable contributions have significantly improved FastOpenAPI, reinforcing my belief in the strength and future of open source communities!

FastOpenAPI: Generate OpenAPI Schemas for Any Python Framework

Mr Fatalyst — Sat, 22 Mar 2025 10:53:51 +0000

Developing APIs is a crucial part of modern software projects, and OpenAPI is the de facto standard for documenting APIs. While FastAPI seamlessly integrates OpenAPI schema generation and documentation, what if you prefer using frameworks like Flask, Falcon, Sanic, or others? FastOpenAPI addresses exactly this need.

What is FastOpenAPI?

FastOpenAPI is a Python library inspired by FastAPI and built upon Pydantic v2, designed to simplify the generation and integration of OpenAPI schemas with virtually any popular Python framework. Importantly, FastOpenAPI uses "proxy routing": you write routes in a FastAPI-like style, and FastOpenAPI automatically registers them with your chosen framework.

Key Features:

Support for Falcon, Flask, Quart, Sanic, Starlette, Tornado.
Proxy routing with automatic registration.
Convenient FastAPI-style API.
Automatic documentation generation (Swagger UI, ReDoc).
Strong data validation and typing via Pydantic v2.

How it Works

FastOpenAPI employs a system of adapters (routers), each integrating with a specific framework:

BaseRouter: Contains shared logic for schema and documentation generation.
Specialized routers (FlaskRouter, SanicRouter, etc.) extend BaseRouter.

Minimal Flask API Example:

from flask import Flask
from pydantic import BaseModel

from fastopenapi.routers import FlaskRouter

app = Flask(__name__)
router = FlaskRouter(app)

class UserResponse(BaseModel):
    username: str

@router.get("/user", tags=["User"], response_model=UserResponse)
def get_user(username: str):
    return UserResponse(username=username)

if __name__ == "__main__":
    app.run(port=8000)

Go to http://localhost:8000/docs to see swagger for example.

You can try it:

Router Composition

FastOpenAPI supports convenient API structuring through router composition, similar to APIRouter in FastAPI. For example, creating versioned APIs:

from flask import Flask
from pydantic import BaseModel

from fastopenapi.routers import FlaskRouter


app = Flask(__name__)
main_router = FlaskRouter(app)

api_v1 = FlaskRouter()
api_v2 = FlaskRouter()

class UserResponse(BaseModel):
    username: str
    version: str

class UserResponseV2(BaseModel):
    login: str
    version: str

@api_v1.get("/items", tags=["Users", "v1"], response_model=UserResponse)
def items_v1(name: str):
    return UserResponse(username=name, version="1.0")

@api_v2.get("/items", tags=["Users", "v2"], response_model=UserResponseV2)
def items_v2(name):
    return UserResponseV2(login=name, version="2.0")

main_router.include_router(api_v1, prefix="/api/v1")
main_router.include_router(api_v2, prefix="/api/v2")

if __name__ == "__main__":
    app.run(port=8000)

Go to http://localhost:8000/docs:

If you prefer ReDoc, you can go to http://localhost:8000/redoc:

Generated Documentation

Once the server is running, documentation is automatically available:

Swagger UI: http://localhost:8000/docs
ReDoc: http://localhost:8000/redoc
OpenAPI JSON: http://localhost:8000/openapi.json

Performance Considerations

The project's repository includes basic benchmarks showing that FastOpenAPI introduces only a modest overhead (approximately 2-5%), which is a small price to pay for robust data validation and automatic documentation.

Who Should Use FastOpenAPI?

Developers wanting OpenAPI support without migrating from their preferred framework.
Teams using multiple frameworks seeking standardized API documentation.

Installation and Usage

# Choose installation based on your preferred framework pip install fastopenapi[falcon] pip install fastopenapi[flask] pip install fastopenapi[sanic] pip install fastopenapi[starlette] pip install fastopenapi[tornado]

Conclusion

FastOpenAPI is an open-source library that simplifies the addition of OpenAPI specifications to existing Python projects across various frameworks, offering a balance of convenience, flexibility, and performance.

Project Repository:

mr-fatalyst / fastopenapi

FastOpenAPI is a library for generating and integrating OpenAPI schemas using Pydantic v2 and various frameworks (AioHttp, Falcon, Flask, Quart, Sanic, Starlette, Tornado).

FastOpenAPI is a library for generating and integrating OpenAPI schemas using Pydantic and various frameworks

This project was inspired by FastAPI and aims to provide a similar developer-friendly experience

📦 Installation

Install only FastOpenAPI:

pip install fastopenapi

Install FastOpenAPI with a specific framework:

pip install fastopenapi[aiohttp]

pip install fastopenapi[falcon]

pip install fastopenapi[flask]

pip install fastopenapi[quart]

pip install fastopenapi[sanic]

pip install fastopenapi[starlette]

pip install fastopenapi[tornado]

🛠️ Quick Start

Step 1. Create an application

Create the main.py file
Copy the code from an example
For some examples uvicorn is required (pip install uvicorn)

Examples:

Click to expand the Falcon Example

from aiohttp import web
from pydantic import BaseModel
from fastopenapi.routers import AioHttpRouter

app = web.Application()
router = AioHttpRouter(app=app)


class HelloResponse(BaseModel):
    message: str


@router.get("/hello", tags=["Hello"], status_code=

…

View on GitHub

The project is still evolving, and I’d love any feedback or testing from the community!