Design and Implementation of a Centralized Swagger Documentation Registration Center with Knife4j Integration

Author 阿Q introduces the initial use of swagger and swagger‑ui for API documentation, noting the poor UI of the native version and the improvement achieved by switching to the open‑source knife4j component.

The main focus is on the issues that arise after integrating knife4j in a Spring Security‑protected project, including the need for custom rule filtering, loss of documentation when services stop, difficulty showing multiple versions during development, and the heavy overhead of integrating knife4j in each microservice.

Two Documentation Aggregation Modes

Gateway Aggregation Mode

In this pattern a gateway forwards requests to each microservice, retrieves the /v2/api-docs JSON from the service’s swagger endpoint, and renders the combined UI using a single swagger‑ui instance. While it reduces the number of integrations, it introduces security concerns, forces documentation to be published to production, and does not solve the multi‑document development problem.

Centralized Registration Mode

Each microservice, on startup, obtains its registration information from a service‑discovery system such as Nacos or Eureka, extracts its swagger definition, and posts it to a dedicated swagger‑register‑server . The server stores group metadata in a group_info table and the raw JSON in a swagger_json table, then serves the aggregated list via /swagger‑resources and individual documents via a custom /swagger/detail endpoint. Only the registration server needs to embed swagger‑ui , keeping other services lightweight.

Implementation Details

The registration server provides four key APIs:

POST /register – receives group and JSON data, performs upsert based on unique groupName and appName .

GET /swagger‑resources – returns a list of SwaggerResource objects (name, url, swaggerVersion) built from the group_info table.

GET /swagger/detail/{group} – fetches the stored JSON from swagger_json for rendering.

CRUD operations for dynamic updates.

The swagger‑spring‑boot‑starter is a client library that automatically scans the application’s Swagger metadata (via SwaggerMvcGenerator.getSwagger() ), then registers it using SwaggerRegistryService.registry() . It supports both direct server URL registration ( swagger.config.server‑url ) and service‑discovery registration ( swagger.config.service‑id ), and works with both Nacos and Eureka through the common spring‑cloud‑commons interfaces.

Deployment and Usage

To run the registration server, provision a MySQL database and a Nacos instance, execute the provided init.sql script to create the tables, and start the Spring Boot application. The UI can be accessed at /doc.html (e.g., http://swagger.kdyzm.cn/doc.html ).

Microservices add the starter dependency, configure their Swagger metadata (base‑package, description, group name, etc.) in application.yml , and activate the swagger profile. Upon startup the service automatically uploads its documentation to the registration server.

Additional Considerations

Switching between direct‑connect and discovery modes is controlled by the presence of swagger.config.server‑url . Unique appName and name values are required to avoid duplicate groups; currently the server does not support deletion, so accidental uploads must be removed manually via contact.