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

61–70 of 78 posts

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

#61

Post by simplesager »

ivan888 wrote: post #21
DidYaWipe wrote: post #4

This is probably cool and useful, but there's no way to know how much of the API you're covering, right? I find that the real shortage of tools exists going the other way: from OpenAPI to code. The ecosystem has proven to be a huge disappointment there, comprising a janky collection of defective tools that still (years later) don't support version 3.1 (a critical update).

I think going from code to OpenAPI makes a lot more sense, at least for strong typed languages. And even if not directly translated from code, at least closer to the actual code, in annotations or something. Generating the spec from code removes a step, where you simply need to update code, rather than update the spec then update the code

Completely agree. Keeping the openapi spec as tightly coupled to types in code builds a single source truth from your development to your deployment

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

#62

Post by ramraj07 »

pattycakes wrote: post #51
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

Exactly this, I’ve been a python guy which is apparently not the main language used by most api developers or what? Is there nothing like FastAPI in js land? I do start my APIs by writing the openAPI spec, only it’s written in pydantic inside FastAPI and turns out this also creates the actual API lol.

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

#63

Post by enobrev »

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…

The API library I wrote for my last couple projects required the developer to fill in the openapi spec specifics and said spec was the part of the API itself, making it difficult to add something to the API that wasn't also in the spec.

Incoming request params, became validated and casted object properties. Outgoing response params were validated and casted according to spec.

In the end I think it worked really well, and loved not needing to maintain the spec separately. The annoying bit was adjusting the library when the spec changed.

And some gnarly bits of the spec that weren't easy to implement logically.

At any rate, it also made for a similar experience of considering the client experience while writing/maintaining the api.

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

#64

Post by jpalawaga »

mdasen wrote: post #28
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…

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…

swaggest allows you to define your inputs and outputs, and generate docs from them.

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

#65

Post by Petermarcu »

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…

http://typespec.io

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

#66

Post by BillyTheKing »

Petermarcu wrote: post #65
tevon wrote: post #35

Earlier quoted context omitted.

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…

http://typespec.io

oh thanks a lot for sharing - I was looking for something just like this! Something like this + hurl is the perfect combination to sketch out APIs imo

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

#67

Post by tczMUFlmoNk »

Is this comparable to Akita? https://www.akitasoftware.com/

> By watching API traffic live and automatically inferring endpoint structure, Akita bypasses the complexity of implementing and maintaining monitoring and observability.

> […]

> - Export your API description as an OpenAPI spec.

(Not affiliated, nor am I a user of either of these.)

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

#68

Post by physicsguy »

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…

I prefer going the other direction in practice, autogenerating the spec from the code e.g. with drf-spectacular for Django.

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

#69

Post by steve_rambo »

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…

You don't need annotations for descriptions, they get picked up from javadoc-style comments which you should have anyway. Same with asp.net.

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

#70

Post by BerislavLopac »

paholg wrote: post #25
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…

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…

You are correct about YAML, but OpenAPI is not YAML -- it just commonly uses it as for the textual representation. As others mentioned it, JSON is an alternative, although it doesn't make it much easier to write the code directly.

Sadly, there is a distinct lack of tools to make spec-first development easier. At the moment, Stoplight [0] is the only game in town as a high quality schema editor, but it requires payment for any more significant usage.

[0] https://stoplight.io/

Post reply on HN