api: add api spec to the project

[BrunoRosendo]

In order to better control and organize our API specification, we should have it documented and maintained, even if the endpoints have not yet been created. The best option is probably OpenAPI but feel free to try something else if you feel like it'd fit best here (a docusaurus documentation could be nice but it's a lot more work and probably overkill)

[Sirze01]

Hi everyone! I added the openapi documentation for the API and the swagger-ui to explore it. Check the README for more details. If you have some feedback or suggestions please tell me...

[Sirze01]

I haven't worked on the issue for some time, so when I picked it up again I thought it was best to go back to the drawing board and figure out what our options where to properly document the API.

I had some requirements for the documentation, some of which we discussed in one of the weekly meetings some time ago:

• It needs to integrate well with the TBD approach of Spring
• It should require no or very small source code changes apart from the endpoint documentation itself
• It should have minimal configuration required
• Should be easily and automatically deployed, preferably using GitHub wiki

With this goal in mind I found 3 contenders:

• Springdoc Openapi
• Spring Rest Docs
• Restdocs API Spec

Springdoc Openapi

Implementation: api/api-spec-openapi

This first approach it is the one I presented some time ago. It relies on documenting the controller in the implementation itself, resulting in a very cluttered implementation, violating the TBD pattern we are trying to keep.

The result of the documentation it is an openapi specification. This specification is served along with a swagger interface in the resulting server executable in the endpoint /swagger-ui.html.

The specification file cannot be easily obtained in order to be displayed in the wiki or outside of the deployed server, making it a unsuitable option. The upside of this method is the relatively better schema and constraint handling.

Spring Rest Docs

Implementation: api/api-spec-spring_rest_docs

This is the official way of documenting API's provided by the Spring framework. The way it works is by generating adoc code snippets along with test execution. The information for the snippet generation is declared in the tests for that endpoint. Those snippets can be later included in another "hand-edited" adoc file that is compiled using a gradle task generating a standalone html page that can be used either in the wiki or served however we see fit (this process can be automated with an action).

The documentation comes out both as very "professional" and verbose. The clear downsides of this option it the need to include the snippets and write descriptions for each operation, something that might become somewhat tedious. The interface for documenting it is also a little worse than the one provided by Springdoc.

Restdocs API Spec

Implementation: api/api-spec-restdocs_api_spec

This is a project based on Spring Rest Docs, making use of the TBD approach to generate parts of an openapi specification. It uses a very similar interface as Spring Rest Docs with some minor modification to accommodate the summary and description fields of the specification. It still needs an external "hand-edited" file to save endpoint tags and descriptions, but it brings the documentation closer to the test code.

I find this to be the best approach, as it has the documentation closer to the test code than the other options, and it still leaves us with the benefits of using the openapi specification.

In order to display it we might use something like redoc.

I will wait on some feedback before proceeding to document other endpoints. Please feel free to explore the implementation and to comment what you think.

[BrunoRosendo]

Hey @Sirze01, thanks a lot for the feedback on your options! Here's my opinion from what you've told us (top to bottom):

• I personally dislike this approach because it clutters the source code, which is always the most important thing.
• Looking at the final interface, I like the second and third options equally. Since you already tried them out, we should trust your thoughts and go with the third one. We still have to write some descriptions but that's unavoidable if we want clear API documentation. As for the deployment, we can easily serve it automatically with netlify, the same way we do for NIJobs and website-frontend, as long as we have an HTML or some kind of build. I just have a question, I checked your branch and saw an openapi spec in JSON format. Is that openapi generated automatically with the tests?

Finally, just remember to update your branch since develop had a lot of changes in the meantime.

[Sirze01]

Hey @Sirze01, thanks a lot for the feedback on your options! Here's my opinion from what you've told us (top to bottom):

* I personally dislike this approach because it clutters the source code, which is always the most important thing.

* Looking at the final interface, I like the second and third options equally. Since you already tried them out, we should trust your thoughts and go with the third one. We still have to write some descriptions but that's unavoidable if we want clear API documentation. As for the deployment, we can easily serve it automatically with netlify, the same way we do for NIJobs and website-frontend, as long as we have an HTML or some kind of build. I just have a question, I checked your branch and saw an openapi spec in JSON format. Is that openapi generated automatically with the tests?

Finally, just remember to update your branch since develop had a lot of changes in the meantime.

Hi again, @BrunoRosendo.

Regarding your question, the json file is generated by a task added by the plugin. This task runs the test task and then generates the specification based on the test results. Any restrictions added with the documentation methods will also be checked, raising errors if a field is missing or constraint is offended. I also created a custom task that runs the aforementioned task an then moves the generated file from the build directory to the folder docs.

I'll take care of documenting the rest of the endpoints ASAP using the third method then. Any questions or feedback don't hesitate to @ me.

[BrunoRosendo]

Hey @Sirze01, thanks a lot for the feedback on your options! Here's my opinion from what you've told us (top to bottom):

* I personally dislike this approach because it clutters the source code, which is always the most important thing.

* Looking at the final interface, I like the second and third options equally. Since you already tried them out, we should trust your thoughts and go with the third one. We still have to write some descriptions but that's unavoidable if we want clear API documentation. As for the deployment, we can easily serve it automatically with netlify, the same way we do for NIJobs and website-frontend, as long as we have an HTML or some kind of build. I just have a question, I checked your branch and saw an openapi spec in JSON format. Is that openapi generated automatically with the tests?

Finally, just remember to update your branch since develop had a lot of changes in the meantime.

Hi again, @BrunoRosendo.

Regarding your question, the json file is generated by a task added by the plugin. This task runs the test task and then generates the specification based on the test results. Any restrictions added with the documentation methods will also be checked, raising errors if a field is missing or constraint is offended. I also created a custom task that runs the aforementioned task an then moves the generated file from the build directory to the folder docs.

I'll take care of documenting the rest of the endpoints ASAP using the third method then. Any questions or feedback don't hesitate to @ me.

Perfect 👌