Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Show HN: FastOpenAPI – automated docs for many Python frameworks

github.com

Post reply on HN
Print view View original

21–30 of 85 posts

Re: Show HN: FastOpenAPI – automated docs for many Python frameworks

#21

Post by RadiozRadioz »

dtkav wrote: post #7

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.

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.

Re: Show HN: FastOpenAPI – automated docs for many Python frameworks

#22

Post by dtkav »

RadiozRadioz wrote: post #21
dtkav wrote: post #7

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.

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…

For me it was two things:

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

Re: Show HN: FastOpenAPI – automated docs for many Python frameworks

#24

Post by mariocesar »

jensenbox wrote: post #16
Onavo wrote: post #10

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.

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.

Not a technical reason: I've been using Django Ninja to medium/big app with lot of validation logic, and it was a delight. It was easy to start and integrates well with Django, but I'm moving away from it, not because I dislike it, I still like the approach and ergonomics. However, the project seems somewhat abandoned or at least struggling with updates (last release is in August 2024) and with lots of PRs staled. There are forks like django-shinobi https://github.com/pmdevita/django-shinobi that are moving forward and have releases

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.

Re: Show HN: FastOpenAPI – automated docs for many Python frameworks

#26

Post by ensignavenger »

Onavo wrote: post #10

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.

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

Re: Show HN: FastOpenAPI – automated docs for many Python frameworks

#27

Post by dtkav »

bravura wrote: post #25

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?

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

Re: Show HN: FastOpenAPI – automated docs for many Python frameworks

#28

Post by dtkav »

mr_Fatalyst wrote: post #14
dtkav wrote: post #7

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.

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 API…

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

Re: Show HN: FastOpenAPI – automated docs for many Python frameworks

#29

Post by sastraxi »

Onavo wrote: post #10

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.

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.

Re: Show HN: FastOpenAPI – automated docs for many Python frameworks

#30

Post by dtkav »

ltbarcly3 wrote: post #15

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 techn…

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