Generating API Documentation with Swagger for Spring Boot

In the era of widespread adoption of Spring Boot microservices architecture, constructing clear and interactive API documentation has become a critical component for team collaboration and system maintenance. Swagger (now commonly referred to as OpenAPI Specification) serves as an industry-standard interface description format. When paired with libraries such as springfox or newer versions like springdoc-openapi, it enables the automatic generation of comprehensive JSON and YAML formatted documents, supporting online debugging and testing directly within the browser. This article delves into how to integrate Swagger into a Spring Boot project to achieve automated documentation generation and visual presentation for APIs.
To enable Swagger in a Spring Boot application, you must first introduce the corresponding dependency libraries into your pom.xml or build.gradle. For newer versions of Spring Boot (2.6+), it is recommended to use springdoc-openapi; however, for older versions, springfox remains commonly used. The following examples demonstrate configuration approaches using Maven for both mainstream solutions.

If you are using SpringDoc OpenAPI (Recommended):

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.7.0</version>
</dependency>

If continuing to use SpringFox (Suitable for migrating legacy projects):

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

Once dependencies are introduced, Spring Boot automatically scans and registers Swagger-related configuration classes and beans without requiring manual writing of complex XML configurations.

Core Controller Example: Defining Interface Metadata

The power of Swagger lies in its ability to automatically parse annotation information within Controllers to generate documentation. Developers simply need to add standard annotations on methods or parameters to describe request paths, HTTP method types, request body structures, and response results. Below is an implementation example for a typical user information query interface:

@RestController
@RequestMapping("/api/users")
public class UserController {

    @GetMapping("/{id}")
    public User getUserById(@PathVariable Long id) {
        // Simulate retrieval logic
        return new User(id, "Zhang San", "zhangsan@example.com");
    }

    @PostMapping
    public ResponseEntity<User> createUser(
            @RequestBody CreateUserRequest request) {
        // Simulate creation logic
        return ResponseEntity.ok(new User(request.getId(), request.getName(), request.getEmail()));
    }
}

In the code above, @GetMapping and @PostMapping define GET and POST request paths respectively; @PathVariable is used to extract ID parameters from the URL; and @RequestBody identifies JSON-formatted input data. Swagger automatically recognizes these annotations and generates corresponding documentation descriptions.

Configuring Custom Themes and Layout Styles

The default generated Swagger UI interface is concise but functionally limited, often requiring configuration classes to adjust page styles or enable additional feature modules (such as operation logs, security authentication, etc.). Configure the following in application.yml or application.properties:

springdoc:
  api-docs:
    enabled: true
    path: /v3/api-docs
  swagger-ui:
    enabled: true
    path: /swagger-ui.html
    operations-sorter: alpha
    tags-sorter: alpha
    display-request-body: true

By setting operations-sorter and tags-sorter to alpha, interfaces and tags can be sorted alphabetically, improving lookup efficiency. Enabling display-request-body ensures that request body fields are clearly visible in the documentation. Additionally, you can combine this with Spring Security to implement role-based access control, enhancing security in production environments.

Running Verification: Accessing Swagger UI Interface

After completing configuration, start your Spring Boot application to access the interactive documentation page provided by Swagger. By default, the Swagger UI can be accessed via the following addresses:

  • Old version SpringFox: http://localhost:8080/swagger-ui.html
  • New version SpringDoc: http://localhost:8080/swagger-ui.html or /v3/api-docs

Upon entering the page, users can directly view detailed information for each interface, including HTTP method type, URL path, parameter types, sample data, and expected response structures. Clicking the "Try it out" button allows you to simulate sending requests directly in the browser, observing backend responses in real-time, which significantly reduces debugging costs.

Summary and Practical Recommendations

Swagger API documentation generation not only improves development efficiency but also fosters collaboration between frontend and backend teams. By reasonably configuring dependencies, standardizing annotation usage, and customizing UI styles, developers can quickly build professional-grade API portals. In practical projects, it is recommended to integrate Swagger with CI/CD workflows to automatically verify document consistency before each deployment, ensuring that interface changes are controllable and traceable. As microservices architecture evolves, Swagger will continue to serve as an indispensable infrastructure component within the Spring Boot ecosystem.