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

Show HN: Auto-generate an OpenAPI spec by listening to localhost

github.com

Post reply on HN
Print view View original

51–60 of 78 posts

Re: Show HN: Auto-generate an OpenAPI spec by listening to localhost

#51

Post by pattycakes »

w3news wrote: post #20

When you build an API, please start with the OpenAPI specification, before you write any code for your API. It can be iterative, but for every part, just start with the OpenAPI, and think about what you want from the API, what do you want to send, and what to receive. It is like the TDD approach, design before build. Writing or generating tests after you build the code, is the same as this. It is guessing what it sho…

Waste of time imo if you use a framework like fastapi which generates the spec for you

Re: Show HN: Auto-generate an OpenAPI spec by listening to localhost

#53

Post by boredtofears »

avolpe wrote: post #47
mdasen wrote: post #28

Earlier quoted context omitted.

As a curiosity, how do you feel about languages/frameworks where APIs can be pretty self-documenting? For example, Java/JAX-RS creates pretty self-documenting APIs: @Path("/people") public class PeopleApi { @Path("{personId}") @GET public Person getPerson(@PathParam("personId") int personId) { return db.getPerson(personId); } } It's easy to generate a spec for a JAX-RS class because it has the paths, parameters, type…

For the happy path, the Java code works great, but a good open API spec also includes the following: - examples, they are a pain to write in Java annotations. - multiple responses, ok, invalid id, not found, etc. - good descriptions, you can write descriptions in annotations (particularly post Java 14) but they are overly verbose. - validations, you can use bean validation, but if you implement the logic in code it's…

your example doesn't look any worse than an openapi yaml spec given how easy/frequently you can reach 10+ identation levels for a trivial spec.

you might be able to add descriptions easily, but expressing types in yaml is much more verbose than in a decently typed language.

Re: Show HN: Auto-generate an OpenAPI spec by listening to localhost

#54

Post by refulgentis »

Karrot_Kream wrote: post #41
brosciencecode wrote: post #26

Earlier quoted context omitted.

I get the feeling you may not have gone 0-1 on an API before. In general, you have 1 consumer when you're starting off, and if you're lucky your API gathers more consumers over time. In that initial implementation period, it's more time-consuming to have to update a spec nobody uses. Maintaining specs separately from your actual code is also a great way to get into situations where your map != your territory. I'd ins…

How is adding 10-20 lines, depending on how many structures you're creating, and then re-running a generation tool (or simply just running a build command again depending on your build configuration) time consuming? I've written OpenAPI-first services both at Big Tech for services handling crazy amounts of RPS and at tiny seed startups where we release the API and literally nobody uses it but our app. Sure I've run u…

They are advocating for exactly that: "I'd instead ask: support and use API frameworks that allow you to automatically generate OpenAPI specs

Re: Show HN: Auto-generate an OpenAPI spec by listening to localhost

#55

Post by refulgentis »

madeofpalk wrote: post #43
rad_gruchalski wrote: post #36

Earlier quoted context omitted.

You can write an OpenAPI spec in JSON. You can use Jsonnet to generate your spec from whatever input you need.

JSON is a different kind of yuck to have to author by hand, especially in the volume an api spec tends to be.

I don't like writing structured formats by hand either - at some point, you either need to, as they say in France, split or get off your seat

Either don't write it by hand, i.e. use a generator for the structured format, as the comments advocate for and article is about.

Or, just say you'll never have a spec.

Re: Show HN: Auto-generate an OpenAPI spec by listening to localhost

#56

Post by Falimonda »

tevon wrote: post #35
brosciencecode wrote: post #26

Earlier quoted context omitted.

I get the feeling you may not have gone 0-1 on an API before. In general, you have 1 consumer when you're starting off, and if you're lucky your API gathers more consumers over time. In that initial implementation period, it's more time-consuming to have to update a spec nobody uses. Maintaining specs separately from your actual code is also a great way to get into situations where your map != your territory. I'd ins…

I agree with this as well! OpenAPI spec seems intended to be consumed, not written. Its a great way to convey what your API does, but is pretty awful to write from scratch. I do wish there was a simpler language to write in... JSON-based as well that would allow this approach of writing the spec first. But alas, there is not, and I have looked a loooot. If anyone has suggestions for other spec languages I'd love to l…

Simpler than YAML?

Re: Show HN: Auto-generate an OpenAPI spec by listening to localhost

#57

Post by Rabidgremlin »

w3news wrote: post #20

When you build an API, please start with the OpenAPI specification, before you write any code for your API. It can be iterative, but for every part, just start with the OpenAPI, and think about what you want from the API, what do you want to send, and what to receive. It is like the TDD approach, design before build. Writing or generating tests after you build the code, is the same as this. It is guessing what it sho…

100% agree with you... taking the time to do/go design first greatly improves the quality of the final API...

But as some comments below point out, an OpenAPI spec is a pain to create manually which is why TypeSpec from Microsoft is such a great tool. Lets you focus on the important bits of creating a solid API (model, consistency, best practices) in an easy to use DSL that spits out a fully documented OpenAPI spec to build against! see https://typespec.io/

Re: Show HN: Auto-generate an OpenAPI spec by listening to localhost

#58

Post by paholg »

adawg4 wrote: post #33
paholg wrote: post #25

Earlier quoted context omitted.

I don't want to write OpenApi. Yaml is a terrible programming language, and keeping it in sync with actual code is always a nightmare. I've been using a tool to generate OpenApi from code, and am pretty happy with that workflow. Even if writing the API before logic, I'd much rather write the types and endpoints in a real programming language, and just have a `todo` in the body. You can still write API-driven code wit…

Which tool?

It's going to be very language/framework dependent.

I'm using aide for a Rust/Axum server: https://github.com/tamasfe/aide

Re: Show HN: Auto-generate an OpenAPI spec by listening to localhost

#59

Post by paholg »

rad_gruchalski wrote: post #49
madeofpalk wrote: post #43

Earlier quoted context omitted.

JSON is a different kind of yuck to have to author by hand, especially in the volume an api spec tends to be.

Yes, so use Jsonnet or generate it from some intermediate representation using some alternative method. What’s the problem?

Why though when I can just generate it from my actual code and not have to maintain two copies of my api spec?

Re: Show HN: Auto-generate an OpenAPI spec by listening to localhost

#60

Post by nattaylor »

adawg4 wrote: post #22
nattaylor wrote: post #9

Reminds me of https://github.com/alufers/mitmproxy2swagger which I discovered from this thread https://news.ycombinator.com/item?id=31354130 I generated some specs from that! I ran into trouble keeping them up to date.

Super curious - How did you try keeping them up to date?

Boring things like running the proxy while I did manual QA / ran automated tests.

I quickly realized that if I wanted an up to date spec then I should do it properly in the application

Post reply on HN