SpringDoc + OpenAPI 3 (springdoc-openapi-ui) or Swagger2 v3 (springfox-boot-starter)?

Question

There are 2 ways to add OpenAPI 3 to a Spring Boot project:

<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-ui</artifactId>

https://www.dariawan.com/tutorials/spring/documenting-spring-boot-rest-api-springdoc-openapi-3/

<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>

https://medium.com/@hala3k/setting-up-swagger-3-with-spring-boot-2-a7c1c3151545

There are also migration issues for configuration and annotations. Are there any reasons to make a choice between them for a Spring Boot project?

Answer 1

There's an obvious reason for choosing Springdoc over Springfox in this case. The reason being, springdoc-openapi-ui is a standalone library while springfox-boot-starter pulls in the Spring dependencies transitively. Having taken a look at what the POM looks like, Springfox has a wrapper for many of the Spring projects. Also for the Swagger UI, you need an extra dependency for Springfox.

Thus using Springdoc gives you more control over Swagger integration which is optional, in case you would like to go for a static documentation framework like Spring REST Docs

As far as the migration guide mentioned is concerned, it's for migrating Springfox 2.x projects to Springdoc. Springdoc supports OpenAPI 3.x and not 2.x, while Springfox supports both versions of the specification.