undefined | Better HN

0 pointsavolpe2y ago0 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.

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

0 comments

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

avolpeOP2y ago

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

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.

j / k navigate · click thread line to collapse