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

31–40 of 78 posts

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

#31

Post by rnts08 »

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…

Absolutely, and yes YAML is trash.

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

#32

Post by sbeckeriv »

I wrote a tool for work that does the same thing based on request logs. It would parse each line into a structure then merge the same call point structures down to one spec. It was helpful to see the api but in the end was not that helpful in back filling the openapi spec.

things to consider: - junk data from users will show up. unless your downstream service rejects extra params users will mess with you. - it documents each endpoint but its harder to say if this "user" data is the same as another's endpoints "user" - it is hard to tell if users are hitting all endpoint inputs/outputs without manual review.

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

#33

Post by adawg4 »

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…

Which tool?

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

#34

Post by spondylosaurus »

tkiolp4 wrote: post #29
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…

What’s wrong with designing an API by writing its code? Code itself is a design tool (and usually any decent programming language is a better design tool than YAML)

As someone who documents APIs: it's easy to tell which APIs were designed with intention and which ones were designed on the fly. In part because it's much, much easier to document the former :)

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

#35

Post by tevon »

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…

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 learn!

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

#36

Post by rad_gruchalski »

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 can write an OpenAPI spec in JSON. You can use Jsonnet to generate your spec from whatever input you need.

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

#37

Post by rad_gruchalski »

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…

I don’t agree with you. Write a spec, use generators to generate your servers and clients, and use those generated objects yourself.

The point is twofold: you test your API immediately AND you get a ton of boilerplate generated.

So many products out there just feel like a bunch of separate things with a spec slapped on top. Sometimes the spec doesn’t make sense. For example, the same property across different endpoints having a different type.

Save yourself time and do it right from the get go.

> Maintaining specs separately from your actual code is also a great way to get into situations where your map != your territory.

So yeah, write your spec once and generate all servers and clients from it…

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

#38

Post by bigiain »

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?

I'm thinking using this tool, and having your test suite run through it might work?

At least for people comfortable with doing test driven development.

Write your requirements for your API-driven code as tests first, then document those APIs by running the tests through this tool.

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

#40

Post by bigiain »

sbeckeriv wrote: post #32

I wrote a tool for work that does the same thing based on request logs. It would parse each line into a structure then merge the same call point structures down to one spec. It was helpful to see the api but in the end was not that helpful in back filling the openapi spec. things to consider: - junk data from users will show up. unless your downstream service rejects extra params users will mess with you. - it docume…

Doesn't look like this tool is intended to be deployed into production where "junk data from users" would be encountered. My impression is it's a localhost proxy which only ever sees deliberate test traffic from the developer who's running it on their own machine.

(Although I'd be curious to see something very similar to this running in prod and generating WAF rules and/or alerting on suspicious requests. Kinda like Dynatrace or Splunk, but much more aware of the API documentation and expectations.)

Post reply on HN