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

41–50 of 78 posts

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

#41

Post by Karrot_Kream »

brosciencecode wrote: post #26
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 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 up against the occasional sharp edge/incompatibility with some form of nested structure and the generator we used but it was usually a minor diversion and represented 20-30 min of wasted time for the occasional badly-behaving endpoint.

I'm even writing a side project now where I'm defining the API using OpenAPI and then running a generator for the echo Go framework to generate the actual API endpoints. It takes just a few minutes to create a new API.

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

#42

Post by madeofpalk »

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…

Unfortunately OpenAPI specs suck to write manually.

Generating OpenAPI spec from the server code has always felt significantly better for me.

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

#43

Post by madeofpalk »

rad_gruchalski wrote: post #36
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…

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.

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

#47

Post by avolpe »

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…

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 not easy to add that to the generated spec.

See for example this from springfox https://github.com/springfox/springfox/blob/master/springfox...

It's overly verbose and the generated open API spec is not very good.

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

#48

Post by radicality »

I’ve only glanced at the code on mobile, but am I reading this right? It seems like this does pretty much… nothing apart from writing everything to a .har file, and then calls out to a separate library called “har-to-openapi” to do the actual work?https://github.com/jonluca/har-to-openapi

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

#49

Post by rad_gruchalski »

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.

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

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

#50

Post by jzig »

dxbednarczyk wrote: post #46
jzig wrote: post #44

Feature request: a browser extension that intercepts HTTP requests for any given website (instead of localhost) and documents their API :)

See https://github.com/AndrewWalsh/openapi-devtools

Very cool. Thank you!
Post reply on HN