Some people have an aversion to "goto" statements, and Java annotations are even worse, they're a "comefrom" statement, where you end up executing code before or after your function based on this annotation, so it makes the code really annoying to follow.
Java examples which show trivial code annotated with @POST or @Path are not representative of production systems, where you may have a lot more annotations for your DOM, documentation, and in some cases, you actually have more annotation boilerplate than you have code in the handler/controller.
Having annotations interleaved within your logic makes it difficult to provide good API documentation, and it's hard to automatically refactor, because your boilerplate is interleaved with real code. With an approach like this grumpyrest, you can put all your machine generated code into a package, and simply connect it to your hand written code with a little bit of glue. It makes spec-driven development much easier.
OpenAPI is very popular, and annotation based frameworks make it more difficult to integrate with it. If you generate API docs automatically from code, as with JAX-RS, it's easy to break things by accident because nobody audits machine generated docs. If you reverse the approach, and do spec-driven development, you code review the API behavior, and the code follows, which is a better model, in my opinion. Grumpyrest looks like it makes integration with spec-driven workflows quite easy.
A word of caution to the author; if this takes off, you will be inundated with issues and PR's, since people will use this in ways you never dreamed of. I'm experiencing that kind of onslaught in something I open-sourced for Go for REST API's.
> Some people have an aversion to "goto" statements, and Java annotations are even worse, they're a "comefrom" statement, where you end up executing code before or after your function based on this annotation, so it makes the code really annoying to follow.
I like this comment so much because I would have described annotations as a "comefrom" myself... but then I probably read that somewhere and forgot about it.
> Grumpyrest looks like it makes integration with spec-driven workflows quite easy.
This is interesting to me because I always thought about it the code-first-generate-documentation way, and I always wondered if/how I can derive all the meta-data from the code which, admitted, annotations make much easier because they are statically accessible.
Doing it the spec-first way is something I should definitely consider.
> A word of caution to the author; if this takes off, you will be inundated with issues and PR's, since people will use this in ways you never dreamed of. I'm experiencing that kind of onslaught in something I open-sourced for Go for REST API's.
Thank you for the warning. Do you have any advice on how to prepare for that?
> Some people have an aversion to "goto" statements
That's because 1 of the 1st things they teach at school is that "goto" is bad, but no 1 really gets why (at the time). It just goes into their brains and this carries forward.
> Java examples which show trivial code annotated with @POST or @Path are not representative of production systems
That happens with every language though. There are disasters everywhere.
Regarding api docs, my experiences have steered me to generate-docs-from-code. The problem with writing api docs first and generate code after, is that writing api docs is a 'business' collaboration, which eventually is not done by developers. The code is a 'technical' model of that api contract. The developers are limited by the api-to-code generator and even more importantly, the limitations of the coding language.
As a result, the 'business' comes up with the api contract, discussed and approved by multiple departments and committees, before the 'technical' developers have to show it is impossible to implement with current technology.
Some people have an aversion to "goto" statements, and Java annotations are even worse, they're a "comefrom" statement, where you end up executing code before or after your function based on this annotation, so it makes the code really annoying to follow.
Java examples which show trivial code annotated with @POST or @Path are not representative of production systems, where you may have a lot more annotations for your DOM, documentation, and in some cases, you actually have more annotation boilerplate than you have code in the handler/controller.
Having annotations interleaved within your logic makes it difficult to provide good API documentation, and it's hard to automatically refactor, because your boilerplate is interleaved with real code. With an approach like this grumpyrest, you can put all your machine generated code into a package, and simply connect it to your hand written code with a little bit of glue. It makes spec-driven development much easier.
OpenAPI is very popular, and annotation based frameworks make it more difficult to integrate with it. If you generate API docs automatically from code, as with JAX-RS, it's easy to break things by accident because nobody audits machine generated docs. If you reverse the approach, and do spec-driven development, you code review the API behavior, and the code follows, which is a better model, in my opinion. Grumpyrest looks like it makes integration with spec-driven workflows quite easy.
A word of caution to the author; if this takes off, you will be inundated with issues and PR's, since people will use this in ways you never dreamed of. I'm experiencing that kind of onslaught in something I open-sourced for Go for REST API's.