Show HN: FastOpenAPI – automated docs for many Python frameworks
github.com
github.com
While working on a project that required OpenAPI docs across multiple frameworks, I got tired of maintaining separate solutions. I liked FastAPI’s clean and intuitive routing, so I built FastOpenAPI, bringing a similar approach to other Python frameworks (Flask, Sanic, Falcon, Starlette, etc).
It's meant for developers who prefer FastAPI-style routing but need or want to use a different framework.
The project is still evolving, and I’d love any feedback or testing from the community!
Just one thing that I tried to find more information about is: are you suppose to rely on the prefix for specifying api version?
Disclaimer: I'm on a phone while writing this, so I just might have missed something obvious
other then that, kudos for releasing this package!
Personally, I prefer using router composition for flexible route organization. You can see a clear example of this with Flask here: https://github.com/mr-fatalyst/fastopenapi/tree/master/examp...
In this example, routes are split into routers by entities, which are then grouped into an api_v1 router, and finally, this api_v1 router is added to the main router.
My use case for fastAPI is very specific (we only maintain APIs for ML models), so I'm curious to learn about this.
The full list of frameworks is: Falcon, Flask, Quart, Sanic, Starlette, and Tornado.
Looks like I accidentally missed Quart in some parts of the docs—my bad, apologies! It’s included in the examples.
One great too for that is TypeSpec[0].
This also allows thinking about the API first and ensures that what's documented is what's implemented.
Doesn't most people? Until you're no longer in the happy path of whatever you use to generate code.
That coupled with the relative immaturity of the python async ecosystem leads to lots of rough edges. Especially when they deploy these things into heavily abstracted cloud ecosystems like Kubernetes.
FastAPI also trys to help by making it "easy" to run sync code but that too is an abstraction that is not majorly documented and has limitations.
> FastOpenAPI is a library for generating and integrating OpenAPI schemas using Pydantic v2 and various frameworks (Falcon, Flask, Sanic, Starlette, Tornado).
And, no, the analogy to painting dogs isn’t valid. I’m sure you’re right to say that the projects you worked on did not end well but that single anecdote doesn’t invalidate all of the other projects which didn’t have that problem, much less the desire other people might want for a similarly-easy experience when using different frameworks.
The thing about not marking compute bound or synchronous tasks properly was the cause of a gnarly performance issue with an application at a previous employer, and such mistakes are easy to make -- I'll give you that.
(As an aside, is there an open-source UI for docs that actually looks good - professional quality, or even lets you try out endpoints? All of the decent ones are proprietary nowadays.)
For a clean, documentation UI, the best open-source options right now are probably Swagger UI and ReDoc. FastOpenAPI uses both by default:
- Swagger UI: interactive, lets you try out endpoints live. - ReDoc: more minimalist and professional-looking but static.
If you're looking for something different, you might check out RapiDoc, which is also open-source, modern, customizable, and supports interactive API exploration.
Actually, returning a Pydantic model directly isn't mandatory—it's just a recommended and convenient approach to ensure automatic data validation and documentation.
If you prefer, you can keep your existing route handlers as-is, returning dictionaries or other JSON-serializable objects. FastOpenAPI will handle these just fine. But using Pydantic models provides type safety and cleaner docs out of the box.
Is there any way to not need the response_model= and instead infer from return type?
Right now, explicitly specifying response_model is required, but only for documentation purposes. Python's type annotations alone aren't sufficient for reliable inference at runtime. I'm considering adding automatic inference support not only for models but also for basic types (like built-in primitives).
Here's my project repo: https://github.com/taskiq-python/aiohttp-deps
https://github.com/mr-fatalyst/fastopenapi/tree/0.5.0-dev
Example: https://github.com/mr-fatalyst/fastopenapi/tree/0.5.0-dev/ex...
Then there's Rust's Tokio for the things that need performance.
Two big deals of Trio and AnyIO are channels (similar to Go's channels), the ability to return data from starting a task in a nursery/task group:
async def my_consumer(task_status = anyio.TASK_STATUS_IGNORED):
tx, rx = anyio.create_memory_object_stream()
task_status.started(tx)
async for message in rx:
...
async def my_producer(tx):
await tx.send("hello")
await tx.send("world")
await tx.aclose()
async def main():
async with anyio.create_task_group() as tg:
tx = await tg.start(my_consumer)
tg.start_soon(my_producer, tx)So many issues with type duplication due to weird footguns around the generated types. Lots of places where we needed to essentially duplicate a model due to the generated types not allowing us to modify or copy parts of a generated type's value and so forth.
Any recommendations?
I'm not sure what you mean by concise complete subset, but in the past I had good success with custom rules in spectral [0].
I've tried prunes operations while preserving referenced components using redocly.
I've tried openapi-extract CLI to extract only components I reference.
And I've tried openapi-format CLI.
They all give different results, and I can't tell whether I am pruning too much or too little.
And yes I'm using spectral at the end, but it doesn't necessarily show it you're missing something that isn't referenced in the final output.
I'm a fan of spec-first (i worked on connexion), but I've noticed that code-first seems to be more popular.
I think the popularity of code-first tools (like FastAPI) mostly comes from the convenience of quickly defining and changing APIs right alongside your code.
There are a bunch of trade-offs based on your starting point and where you want to get to.
I have found Spec-First is useful for a retrofit and having large org API design standards, but then code first can be helpful again if you are writing a framework to have consistent endpoints by default (like pocketbase's API).
If you're maintaining a private API then it makes sense to optimise for individual developer velocity and code-first seems like a good fit.
The upfront cost is higher than the 10 lines it takes to make a working FastAPI app, but once you're past that it becomes a huge timesaver. It's an investment that pays dividends, so definitely for the patient programmer with a long-term view. Not to mention the automatic improvement in API consistently.
I worry slightly about AI completion generating all the code-first boilerplate before people give spec-first a try. It's the same speedup, but with none of the determinism or standardisation.
- collaborative live API design/review with rapid iteration.
- developing automation on openapi specs to help teams avoid making backwards compatibile changes.
It is much easier to catch things in design.
spec-first is probably most useful for large public APIs.
You can publish a working spec long before worrying about any sort of technical implementation, which means you can get feedback from the other teams involved, which can save an immense amount of time. Additionally, the other team can start working from your clear spec sooner, so you unblock them, AND there are all kinds of great mocking tools to fake your api until it's actually done. Oh, and there are libraries that can check your requests/responses in your tests, to ensure you're keeping to the agreed-on spec, so it makes tests more valuable and easier to write, too!
Honestly, even with all that, I wasn't sold on spec first at first because authoring OpenAPI specs SUCKS. It's such a verbose and hard to read and write format. But then I found TypeSpec, and I haven't looked back. I'm converted our existing specs to TypeSpec and they're half the size or less (usually way less). This is easier to write, but critically, easier to read, which makes PRs against a spec a lot more understandable and meaningful.
If you've ever been on the fence about spec-driven development, give TypeSpec a try. It was a real game changer for me.
I still want to build something that can handle protocol evolution and also do protocol up/down migration on the response (like the stripe API team has done).
The code is the full specification of what a thing does. Anything else is just a watered down version of the thing.
In architecture terms, there is no blue print for the blue print, typically. This is a fundamental misconception some people have about software design vs. traditional engineering/architecture.
When designing buildings, you put all your effort in the blue print. And then you build it. With software, you put all your effort in the blue print (i.e. the source code). And then you run/compile it. In neither case is it valuable to have a meta blue print. At best you might do some sketching, prototyping, modeling. But these are activities intended to learn, not to document. 3D printing makes the metaphor more obvious maybe. Because it makes engineering more similar to software development. All the key work is digital.
If you just need docs then maybe that works for you. OpenAPI can do so much more though - it can specify a protocol.
If you can't see why a protocol specification is different from an implementation of that protocol then I don't know what to tell you.
Many internet standards & protocols are typically developed together with their reference implementation. E.g. the IETF is pretty good at that for things like HTTP. Waterfall just doesn't work for anything moderately complicated.
If it's simple, a lot of upfront documentation is not going to be that helpful. If it's not, a proof of concept implementation that irons out all the design mistakes and that proves it is any good would be a good idea. There aren't a lot of good protocols that get developed without those.
Anyway, the article is about slapping openapi specs on python web frameworks, which suggests it's being used in its usual role of documenting existing APIs here. And for REST protocols, python is a great tool to prototype those.
Right now I'm shifting to FastAPI + Django since much of my logic is already in Pydantic classes, and authentication is token based, so FastAPI mainly is a wrapper for my Django app. Still, it doesn't feel ideal. I would prefer to use django-shinobi, but when I first try to migrate to FastAPI I did it most of the hard stuff in a day
If you're considering options, I recommend giving django-shinobi a try. I hope it gains more traction and involves more maintainers.
Django ninja creator here
The project is used in a lot of critical infrastructure so we are prasing more about stability and performance rather then newest featers
On the other hand we prise all fork and keep an eye on them on the features that seems interesting
BTW next relrase is planned by the end of this month
Cheers
First off, I just want to say how grateful I am for your work. I know how challenging it can be to maintain opensource projects, and I truly appreciate the effort
Wishing you all the best.
This is a bit unrelated, but something thats been on my mind, how are things for you with everything going on in Ukraine? I cant imagine how difficult it must be to deal with such situation while also staying active in open source
We build all kinds of frameworks with routing and request/response validation, and then extract that into OpenAPI format, ofteng having to jump through hoops to adapt our internal data types and structures into those supported by JSON Schema. Instead, we could be doing the opposite: writing the OpenAPI spec first, and use tooling to make routing and validation based on it in an automated way. That has been done before [0] [1], but we're still just scratching the surface of what is possible.
Yes, I am aware that it's not easy to manually write the specs using JSON or even YAML, but we need a better focus on tooling around it; currently only Stoplight [2] gives a solid level of support in that area.
[0] https://connexion.readthedocs.io
P.S. I'd prefer FastAPI as well ;)
Asyncio in Python is a poor feature that splits the language's ecosystem into 2 mutually-incompatible worlds, something Python only gets away with because it's too big to fail.
Meanwhile we've had Gevent for decades now. It gives us async that you can forget you have. Because rather than making code async, it makes the VM async.
Gevent could have been merged into CPython, but they chose explicit "structured concurrency" and the rest is history. History of sometimes moving forward and sometimes straying from the path and getting lost.
And lost Python's asyncio is. PDB, which lots of other debuggers base on, is still broken (cannot use await). The ecosystem? IPython uses asyncio internally so it cannot easily be embedded in a working async program. The only embeddable REPL I was able to find is this: https://github.com/prompt-toolkit/ptpython/blob/master/examp...... actually, it looks like someone is working on adding `await` support to PDB now, years after asyncio's first release.
Overall, lots of churn to get something (maybe) as good as Gevent, which we had in Python 2.7, or even before.
If a similar amount of effort was spent on first-class support for code hot-reloading and live program inspection, we would get a massive boost of productivity. But somehow even otherwise bright people choose to reimplement working solutions into something objectively worse, meanwhile our development/debugging loop still emulates loading punchcards into mainframes.