Show HN: FastOpenAPI – automated docs for many Python frameworks

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!

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.

Does the flask extra also support quart?

[dead]

[dead]

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

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

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

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

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.

Maybe Rapidoc?

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.

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.

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.

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

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

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.

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.

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/

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.

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.

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

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

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.

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

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