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

71–78 of 78 posts

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

#71

Post by thiht »

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…

I absolutely hate the approach of scattering routing instructions everywhere via annotations. Nothing beats a router.go file with all the endpoints declared in the same place. Routing annotations is a bad idea that caught up just because it looks clever.

Looking for the handler for ˋGET /foo/{fooID}/barˋ is terrible in a codebase using annotations.

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

#72

Post by lttlrck »

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?

Jsonnet introduces another (flawed) language?

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

#73

Post by dingi »

Although this feels like a ok-ish approach to just serve API docs to users, you are missing the whole point of specs if you use this approach. I have started to extensively use spec-first approach with open API. You wouldn't believe how many hours it saved for me despite the initial cost of time to get things started. For example, No need to tediously write DTOs ever, just have them generated using API spec. Need an SDK for API consumers, just generate an SDK using the spec for almost all the popular languages. While using Open API as just an API documentation is fine, it is a waste of potential that Open API provides.

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

#74

Post by avolpe »

steve_rambo wrote: post #69
avolpe wrote: post #47

Earlier quoted context omitted.

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.

You are right, for Spring Boot, the relatively new springdoc supports javadoc[1] as descriptions, which is better than the annotation.

[1] https://springdoc.org/#javadoc-support

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

#75

Post by eddd-ddde »

thiht wrote: post #71
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…

I absolutely hate the approach of scattering routing instructions everywhere via annotations. Nothing beats a router.go file with all the endpoints declared in the same place. Routing annotations is a bad idea that caught up just because it looks clever. Looking for the handler for ˋGET /foo/{fooID}/barˋ is terrible in a codebase using annotations.

At work they force me to use NestJS. Want to make a new GET endpoint? Find the controller class, add a method, add a get decorator, add an authentication decorator, add a param decorator, add openapi decorators, and if you are feeling helpful, add openapi decorators to every property of every object you take in or return.

I hate decorators so much, just let me use regular data as code.

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

#76

Post by adawg4 »

raybb wrote: post #45

This is fantastic! I think I'll try to use this to generate the spec for openlibrary.org APIs. We have a few basic ones now but it's a huge pain to write. Someone looked into generating them from the python code but it didn't pan our.

That would be awesome!

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

#77

Post by rrr_oh_man »

radicality wrote: post #48

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

1. What else should it do?

2. I think I like this blunt elevator pitch much better than OP's multiple paragraphs of text...

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

#78

Post by devbit »

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…

OpenAPI specs can save weeks even on small projects, when you need to autogenerate multiple clients in different languages after the API part is ready btw
Post reply on HN