Comment on Show HN: Auto-generate an OpenAPI spec by listening to localhostparentComments−avolpe2yFor 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.−steve_rambo2yYou don't need annotations for descriptions, they get picked up from javadoc-style comments which you should have anyway. Same with asp.net.−avolpe2yYou 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−boredtofears2yyour 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.
Comments
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.
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
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.