swagger-core VS springdoc-openapi

To use the Swagger Annotations or Micronaut OpenAPI annotations add them to compile classpath

Examples include Swagger-Core, SpringFox, NSwag / Swashbuckle, Swagger-express / HAPI-Swagger, Django-REST-Swagger / Flask-RESTplus, etc.

JAX-RS is a java implementation of the OpenAPI Specification. - GitHub - swagger-api/swagger-core

Now Swagger UI is configured and we can start documenting our API. Inside UrlController, above every endpoint, we can use @ApiOperation annotation to add description. Depending on your needs you can use some other annotations.

Here is an example from Swagger APIs GitHub:

Im mostly in C# land nowadays, but this seems to be the java version. I’m not sure it is as deeply integrated, as I think Java has a few popular server frameworks.

In Spring WebMVC/WebFlux, you can use springdoc-openapi to automatically generate an OpenAPI schema from Spring controller implementations. Having an OpenAPI schema enables automatic generation of HTML documentation and client code, which already provides some value.

Springdoc OpenAPI

The issue is that the springdoc-openapi BOM brings an old version of the Spring Framework 6.0, which is incompatible with Spring Boot 3.2. There are several ways to solve this problem: update springdoc, change the order of BOM imports, but the best, in my opinion, is to avoid using the io.spring.dependency-management plugin.

I would suggest using Springdoc

The SpringDoc library comes with lots of annotations to tune your REST API specification precisely. Anyway, that's out of context of this article.

I found SpringDoc, a library that automates the generation of the spec from the source code. It relies on annotations for textual bits (like tags and descriptions), but it also infers stuff from Spring annotations.

This is an API made with Spring Web, uses springdoc-openapi-ui to expose a swagger-ui on http://localhost:8080/swagger-ui/index.html

Libraries like Springdoc or Springfox can do this. These libraries generate the OpenAPI documentation based on your controllers (+ you can apply the OpenAPI annotations on your controllers). This documentation is then exposed as a REST API, for Springdoc these can be found at /v3/api-docs.