Unlock Powerful API Docs with Knife4j: A Complete Guide for Java Backend Developers

Introduction

Knife4j is an enhanced solution for integrating Swagger API documentation into Java MVC frameworks. It evolved from swagger‑bootstrap‑ui and is named to suggest a small, lightweight, yet powerful tool.

Open‑source Repository

Github: https://github.com/xiaoymin/swagger-bootstrap-ui Gitee:

https://gitee.com/xiaoym/knife4j

Key Features

Simplicity : Left‑menu layout that matches typical Chinese user habits, providing clearer documentation.

Personalized Configuration : Supports custom API base URLs, description attributes, UI enhancements, and more.

Enhancements : Interface sorting, Swagger resource protection, Markdown export, parameter caching, and many other powerful functions.

Feature Preview

Online preview: http://knife4j.xiaominfo.com/doc.html Select different interfaces, authorize, view Swagger entities, and global settings.

Offline documentation export in HTML, Markdown, Word, and PDF formats.

Personalized UI settings, full‑screen API documentation, and search functionality.

Usage Guide

Project structure includes several modules:

knife4j – core Java MVC integration
knife4j-admin – cloud Swagger registration center
knife4j-extension – Chrome extension for Swagger UI
knife4j-service – Swagger service APIs
knife4j-front – static front‑end version for non‑Java languages
knife4j-spring-ui – front‑end UI for Spring projects

For a simple UI skin replacement, you can use the last version of swagger‑bootstrap‑ui (1.9.6) or knife4j‑spring‑ui.

Maven Dependencies

Old version:

<dependency>
  <groupId>com.github.xiaoymin</groupId>
  <artifactId>swagger-bootstrap-ui</artifactId>
  <version>1.9.6</version>
</dependency>

New version:

<dependency>
  <groupId>com.github.xiaoymin</groupId>
  <artifactId>knife4j-spring-ui</artifactId>
  <version>${lastVersion}</version>
</dependency>

Spring Boot Monolithic Projects

Include the starter to quickly enable Knife4j:

<dependency>
  <groupId>com.github.xiaoymin</groupId>
  <artifactId>knife4j-spring-boot-starter</artifactId>
  <version>${knife4j.version}</version>
</dependency>

This starter bundles all Knife4j resources, including the front‑end UI jar.

Spring Cloud Microservice Architecture

Each microservice can add the micro‑service starter without pulling the UI resources:

<dependency>
  <groupId>com.github.xiaoymin</groupId>
  <artifactId>knife4j-micro-spring-boot-starter</artifactId>
  <version>${knife4j.version}</version>
</dependency>

When using a gateway to aggregate documentation, you can also add the UI starter:

<dependency>
  <groupId>com.github.xiaoymin</groupId>
  <artifactId>knife4j-spring-boot-starter</artifactId>
  <version>${knife4j.version}</version>
</dependency>

Conclusion

Knife4j effectively resolves the shortcomings of the default Swagger UI, offering a more user‑friendly interface and extensive customization options, and can be integrated into projects written in other languages as well. It is a highly recommended tool for developers seeking powerful API documentation.