Swagger Open API documentation style for Java

[RMCampos]

Hello friends! I've been talking with @annibalsilva about the Swagger documentation style and now I would like to include more opinions on that.

Based on this PR, on SPAR Oracle API, was decided to go with Annotated style instead of a yaml or json file. Adding annotations to all resources, methods, and parameters. However, this way makes the code a bit hard to read, making it quite polluted.

So I want to ask you, what are your opinions on that, and if BC Gov has some definition regarding these two options.

As a matter of comparison, I opened a PR using the yaml file, see it here and the file here

cc: @mishraomp @paulushcgcj @annibalsilva @DerekRoberts @ConradBoydElliottGustafson

[mishraomp]

both approaches have its own benefits, but I believe separating it out to yaml will be a lot cleaner along with some process in CI to make sure, for new endpoints there is an entry in yaml, may be we should make a consistent pattern and follow it across the suite, be it mvc or webflux or node/express or fastapi ....

[mishraomp]

Agreed, let's see what others have to say about this.

[paulushcgcj]

On forest-client, as we're using functional endpoints without annotations, we have methods to encapsulate the documentation. Our approach was to split both the handler and the documentation of each handler into its own class. It makes sense only for functional, but it makes things clear.

Here is an example class

[mishraomp]

is there a way to inject the same from yml file for webflux, just curious if we could use same pattern for OAS3 across the stack for FSA?

[paulushcgcj]

is there a way to inject the same from yml file for webflux, just curious if we could use same pattern for OAS3 across the stack for FSA?

Yes, it is. It's the same thing @RMCampos did for spar. I personally prefer to keep the documentation as close to the code as possible to always remind the developer that when changing something, remember to update the documentation, as who's not seen is not remembered

[RMCampos]

All right! That's a good and fair point @paulushcgcj I hink we can go with annotated style. I'll update my PR. Thanks guys.