Documenting Spring REST APIs with Swagger OAS 3.0

  • Postat în IT
  • la 05-05-2022 15:29
  • de Horatiu Dan
  • 51 vizualizări

by Horatiu Dan


A while ago, I decided to opt for Swagger (UI) as a solution for documenting REST APIs. The APIs are built using Spring Framework (not Spring Boot), more exactly, Spring MVC. For the Swagger integration, I used the Springfox Swagger suite of java libraries.

The reasons of this integration are:

have a way of dynamically documenting the exposed REST APIs have the documentation as close to code as possible so that the two are easily kept in sync and reviewed during code reviews have the docs in standard form (OpenAPI Specification in this case) so that it can be further passed to other tools that accept the standard (e.g MuleSoft), if needed

According to Springfox Reference Documentation, these libraries allow “automating the generation of machine and human readable specifications for JSON APIs written using Spring projects”, thus Springfox OAS was chosen. Moreover, it conforms to OAS 3.0 (previously known as Swagg...