14 ms·
Show HN: FastOpenAPI – automated docs for many Python frameworks
- zapnuk 2y agoWhy not just use fastAPI and have it built into the framework?
- dtkav 2y agoIt sounded to me like they need to retrofit several projects written in different python servers.
- mr_Fatalyst 2y agoSometimes 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 2y agoBecause 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/examples/asyncio-python-embed.py 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.
- ddorian43 2y agoAgree on every word. They'll probably make free threaded shitty too somehow. We'll see.
- mr_Fatalyst 2y agoHey 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!
- pamelafox 2y agoDoes the flask extra also support quart?
- pamelafox 2y agoAnd would it document a streaming API? (With transfer-encoding: chunked) The support for that in OpenAPI is still in progress, I believe.
- mr_Fatalyst 2y agoCurrently, FastOpenAPI doesn't provide built-in support specifically for documenting streaming APIs. As far as I'm aware, support for streaming (chunked responses) in the OpenAPI specification itself is still limited.
- mr_Fatalyst 2y agoYes, Quart is supported. 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.
- raylad 2y agoWhy no Django?
- 2y ago
- memset 2y agoThis 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 2y agoThanks 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 2y agoMaybe Rapidoc?
- dtkav 2y agoNice 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.
- mr_Fatalyst 2y agoThanks! 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.
- dtkav 2y agoYeah, that's fair. Do you maintain any Public APIs or mostly private ones? 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.
- mr_Fatalyst 2y agoYou're right, I'm mostly maintaining different private APIs. In that context, optimizing for individual developer velocity definitely makes code-first more appealing. But you're spot-on about larger orgs and standards—spec-first can simplify collaboration and consistency in those scenarios.
- RadiozRadioz 2y agoSpec-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.
- Onavo 2y agoNo 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.
- stackskipton 2y agoThere is already plenty available that will do what you want. FastAPI or Litestar are two popular ones.
- mr_Fatalyst 2y agoI 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.
- scrollaway 2y agoI believe django-ninja is as good as it gets for this, to be honest. But I wouldn't try to support DRF. Django Ninja implements its own routing and it's a lot better that way.
- Onavo 2y agoDjango Ninja isn't particularly well maintained, there have been a few attempts at forking already. Also I think the author of Django Ninja is more concerned about surviving the war right now.
- Onavo 2y agoI would suggest having an option for pure Django integration, without DRF.
- jensenbox 2y agoWhy are you looking for an alternative to Django Ninja? What about it is deficient for you? Curious because I am about to use it.
- Sodosorry 2y ago[flagged]
- ltbarcly3 2y agoEvery 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.
- dtkav 2y agolol what. Did they not use an asgi server? Sounds like it was just misconfigured.
- tempest_ 2y agoHonestly it is mostly caused by people from the machine learning end of the ecosystem not understanding how cooperative multitasking works and trying to bolt a web framework to their model. 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.
- ltbarcly3 2y agoEverything you say here is true, but if you do an analysis and run benchmarks on non-toy projects you'll quickly find that async Python is a bad choice in virtually every use case. Even for use cases that are extremely IO bound and use almost no compute async python ends up dramatically increasing the variance in your response times and lowering your overall throughput. If you give me an async python solution, I will bet you whatever you want that I can reimplement it using threads, reduce LOC, make it far more debugabble and readable, make it far easier to reason about what the consequences of a given change are for response times, make it resistant to small, seemingly inconsequential code changes causing dramatic, disastrous consequences when deployed, etc etc etc. Plus you won't have a stupid coloring problem with two copies of every function. No more spending entire days trying to figure out why some callback never runs or why it fires twice. Async python is only for people who don't know what they are doing and therefore can't realize how bad their solution is performing, how much more effort they are spending building and debugging vs how much they should have to put into it, and how poorly it performs vs how it could perform.
- adhamsalama 2y agoCool!
- bravura 2y agoI'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 2y agoAre 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 https://github.com/stoplightio/spectral
- bravura 2y agoThe task: I have a massive OpenAPI spec, and I want to drop all operations except for read-only ones. I want to preserve all referenced types, but slim the YAML as much as possible and remove extraneous elements. 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.
- joshgachnang 2y agoInteresting, are you trying to automatically create and use components? Or only show certain fields?
- wseqyrku 2y agoI 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.
- JodieBenitez 2y agoNo Bottle ?
- samstave 2y ago[dead]
- blahhh2525 2y ago[flagged]
- wg0 2y agoAfter 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 https://typespec.io
- monsieurbanana 2y ago> 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.
- wg0 2y agoNah. Has not happened.
- RainyDayTmrw 2y agoBeing able to retrofit declarations/specifications to existing code, both for maintaining backwards compatibility and reducing rework, is very valuable, though.
- lvncelot 2y agoI'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 https://github.com/OpenAPITools/openapi-generator
- gister123 2y agoPython async has been a big mess. I haven’t looked back since moving to a Go + GRPC + Protobuf stack. I would highly recommend it.
- qwertox 2y agoI 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.
- linkdd 2y agoYou should take a look at AnyIO, which unifies asyncio and Trio (it can use both event loops as a backend). 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)
- jt_b 2y agoLove 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.
- These335 2y agoLove 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 2y agoGlad 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.
- Everdred2dx 2y agoNice. 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.
- odie5533 2y agoAwesome 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 2y agoThanks! 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).
- curtisszmania 2y ago[dead]
- BerislavLopac 2y agoI'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 https://connexion.readthedocs.io [1] https://pyapi-server.readthedocs.io/ https://pyapi-server.readthedocs.io/ [2] https://stoplight.io/ https://stoplight.io/
- s3rius 2y agoThat'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 https://github.com/taskiq-python/aiohttp-deps
- mr_Fatalyst 2y agoThanks! I have a draft for aiohttp integration. I think I'll add it later.
- mr_Fatalyst 2y agoI added the draft in 0.5.0-dev https://github.com/mr-fatalyst/fastopenapi/tree/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/examples/aiohttp https://github.com/mr-fatalyst/fastopenapi/tree/0.5.0-dev/ex...
- mr_Fatalyst 2y agoBig 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.