Show HN: FastOpenAPI – automated docs for many Python frameworks

[mr_Fatalyst]

Hey everyone!

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!

[asabla]

for someone that comes primarily from a .net background. This looks fantastic!

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!

[fjdjshsh]

In what context do you need to maintain multiple frameworks?

My use case for fastAPI is very specific (we only maintain APIs for ML models), so I'm curious to learn about this.

[pamelafox]

Does the flask extra also support quart?

[wg0]

After years of development - Now I prefer declarative approach. Specs first, generate the code from it and implement required Interfaces.

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.

[0] https://typespec.io

[monsieurbanana]

> Now I prefer declarative approach

Doesn't most people? Until you're no longer in the happy path of whatever you use to generate code.

[lvncelot]

I'm also really happy with spec first. We're using openapi-generator[1] to generate types from a yaml schema (inverting the more standard approach of generating the yaml) in our Typescript (mostly Nest.js) backends, and export those types as packages for use in our frontends.

[1] https://github.com/OpenAPITools/openapi-generator

[RainyDayTmrw]

Being able to retrofit declarations/specifications to existing code, both for maintaining backwards compatibility and reducing rework, is very valuable, though.

[ltbarcly3]

Every FastApi project I've worked on (more than a few) had an average of less than 1 concurrent request per process. The amount of engineering effort they put into debugging the absolute mess that is async python when it was easily the worst tool for the job is remarkable. If you don't know why it is hilarious that a FastApi project would have less than one concurrent request per process you shouldn't be making technical decisions.

[supriyo-biswas]

I'm not sure about your workload but FastAPI should definitely be able to process more than one request per second assuming that the workload isn't placing a compute bound or synchronous task in the event loop and as long as you're using an ASGI server like Gunicorn for serving requests.

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.

[acdha]

That’s completely off topic, and it says more about the team than the tool.

[dtkav]

lol what. Did they not use an asgi server? Sounds like it was just misconfigured.

[memset]

This is really cool - something I've been looking for with Flask. Cleanest implementation with just the decorator that I've seen.

(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.)

[mr_Fatalyst]

Thanks a lot! Glad to hear it fits your needs.

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.

[ddorian43]

Maybe Rapidoc?

[These335]

Love Flask, but this has always been a missing tool. I have a question though - it seems like you're actually modifying the response data type for Flask routes so that it's a Pydantic model. Is that an optional approach? While I wish that were the official standard, if it is not optional then I think that's quite a big ask for maintainers of existing APIs who want to use your docs library. Regardless, I'm looking forward to trying it out! Looks great.

[mr_Fatalyst]

Glad you like the idea!

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.

[odie5533]

Awesome project! It looks so seamless for Flask! Just switch routers, and you model deserialization/serialization, and /docs. Really impressive work!

Is there any way to not need the response_model= and instead infer from return type?

[mr_Fatalyst]

Thanks!

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).

[s3rius]

That's really neat! I made a project for fastapi-like dependency injection for AioHTTP and it also has OpenAPI spec generation. If I could, I would like to use your library for specs instead of self-written solution.

Here's my project repo: https://github.com/taskiq-python/aiohttp-deps

[mr_Fatalyst]

I added the draft in 0.5.0-dev

https://github.com/mr-fatalyst/fastopenapi/tree/0.5.0-dev

Example: https://github.com/mr-fatalyst/fastopenapi/tree/0.5.0-dev/ex...

[mr_Fatalyst]

Thanks! I have a draft for aiohttp integration. I think I'll add it later.

[gister123]

Python async has been a big mess. I haven’t looked back since moving to a Go + GRPC + Protobuf stack. I would highly recommend it.

[jt_b]

Love Go (and async python, for different reasons) but miss me with the gRPC unless you are building hardened internal large enterprise systems. We adopted it at a late stage startup for a microservices architecture, and the pain is immense.

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.

[qwertox]

I really enjoy Python's asyncio. I'm a big fan of aiohttp and the entire aio* ecosystem.

Then there's Rust's Tokio for the things that need performance.

[mr_Fatalyst]

Big thanks to everyone for the feedback and your reactions! I've started working on version 0.5.0 and will try to include as much as possible of what was highlighted here.

[bravura]

I'm looking for a solution to filter large openapi specs to the most concise complete subset. I've implemented three different variations, two of which appear not to prune enough, and one of which appears to prune too much.

Any recommendations?

[dtkav]

Are you trying to prune inaccessible types or something?

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].

[0] https://github.com/stoplightio/spectral

[servercobra]

Interesting, are you trying to automatically create and use components? Or only show certain fields?

[Everdred2dx]

Nice. This was one of the main shortcomings in Falcon that pushed me to switch some projects to FastAPI. That said FastAPI had many other benefits that went far beyond API specs.

[dtkav]

Nice work! What's your take on spec-first vs. code-first?

I'm a fan of spec-first (i worked on connexion), but I've noticed that code-first seems to be more popular.

[RadiozRadioz]

Spec-first is my preferred approach these days, but I had to grow into it. It didn't make sense early on until I'd written the same boilerplate 100s of times and realised how much time I was wasting.

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.

[DanHulton]

Just to drop another two cents in here - I feel like code-first is great when it's a solo project or very experimental, but when you're working on a larger team, or more to the point, working with other teams, spec-first is invaluable.

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.

https://typespec.io/

[jillesvangurp]

I do the opposite and leave generating openapi docs to an LLM. Mostly that just involves spelling out the obvious; so it's not a particularly hard job for an LLM.

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.

[mr_Fatalyst]

Thanks! I personally prefer code-first because it aligns well with Python’s dynamic nature and feels more natural in daily coding. Spec-first definitely has advantages (especially clarity and collaboration), but it can sometimes introduce friction, especially when rapidly iterating on APIs.

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.

[Onavo]

No love for Django? I am looking for an alternative to DRF and Django-ninja that can optionally generate typed APIs and docs directly from the model definitions.

[ensignavenger]

Django Ninja provides this already for Django, and it is great.

[jensenbox]

Why are you looking for an alternative to Django Ninja? What about it is deficient for you? Curious because I am about to use it.

[mr_Fatalyst]

I actually started working on a router for DRF/Django integration, but Django's project structure made it surprisingly tricky to implement cleanly. It's still on my list though.

[sastraxi]

DRF-spectacular is an okay choice here, you have to manage consistency with return types yourself but the docs and customization options are well done.

[stackskipton]

There is already plenty available that will do what you want. FastAPI or Litestar are two popular ones.

[BerislavLopac]

I'm honestly disappointed how OpenAPI keeps being used over and over as documentation, and extremely rarely as what it excels at, which is specification.

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

[1] https://pyapi-server.readthedocs.io/

[2] https://stoplight.io/

[zapnuk]

Why not just use fastAPI and have it built into the framework?

[mr_Fatalyst]

Sometimes you simply can't switch frameworks—due to legacy code, project constraints, or team preferences. FastOpenAPI is specifically designed for situations like these: it provides FastAPI-style routing and automated OpenAPI docs without forcing you to change the underlying framework.

P.S. I'd prefer FastAPI as well ;)

[karolinepauls]

Because not everyone wants to be a part of the asyncio trend.

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.

[dtkav]

It sounded to me like they need to retrofit several projects written in different python servers.

[JodieBenitez]

No Bottle ?

[adhamsalama]

Cool!

[wseqyrku]

I like this. I think genai could be used to fill in gaps in, for example, Wikipedia with a note that it's AI generated. If anything I think that's a good starting point.