Boost Swagger Docs with SpringDoc and Knife4j: A Practical Guide

Swagger is a popular API documentation tool that generates up-to-date docs and supports online testing, but its built‑in JSON handling has limitations. This guide shows how to enhance Swagger using Knife4j together with SpringDoc.

Discussing Java Swagger Libraries

We compare two widely used Java implementations of Swagger.

SpringFox

SpringFox is the older library with over 5.6K stars on GitHub. Its last release (3.0.0) was two years ago, and it encounters issues with Spring Boot 2.6.x and later.

SpringDoc

SpringDoc is a newer library with over 2K stars, frequent updates, and strong maintenance. It supports both Spring WebMvc and Spring WebFlux projects.

Which to Choose?

If your existing project already uses SpringFox extensively, stick with it to avoid migration costs. For new projects, SpringDoc is recommended due to its active maintenance.

Using SpringDoc with Knife4j

Knife4j is a Swagger UI enhancement library that now also supports SpringDoc. Integration requires only adding a dependency without changing existing usage.

In the

pom.xml

of the

mall-tiny-springdoc

demo, add the Knife4j dependency:

<code><!--Knife4j的Swagger皮肤依赖-->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-springdoc-ui</artifactId>
    <version>3.0.3</version>
</dependency>
</code>

Start the project and visit the default Knife4j UI at

http://localhost:8088/doc.html

.

Test an endpoint that requires JSON request parameters; Knife4j validates the JSON format.

Test an endpoint with long response data; Knife4j provides data folding for better readability.

Knife4j Microservice Solution Update

The previously released microservice aggregation solution for Swagger APIs now supports the latest Spring Cloud version.

Implementation Principle

The ideal solution uses a gateway as a unified entry point, aggregating documentation from all microservices.

micro-knife4j-gateway : gateway service that aggregates API docs and includes the UI package.

micro-knife4j-user : user service, a regular API without UI.

micro-knife4j-order : order service, a regular API without UI.

Project Repository

https://github.com/macrozheng/springcloud-learning/tree/master/micro-knife4j

Conclusion

Libraries like Knife4j that enhance Swagger without altering its core usage greatly improve the developer experience. More such UI‑enhancement tools would make Swagger even more user‑friendly.

Source Code

https://github.com/macrozheng/mall-learning/tree/master/mall-tiny-springdoc