Swagger API Documentation

In the process of frontend-backend separation development, the frontend is often handled by professionals, and we usually only need to focus on the interfaces provided to frontend developers for integration. As our work becomes further specialized, it becomes essential to provide a reference document for frontend developers.

However, maintaining a separate project solely for documentation is neither practical nor efficient. Moreover, as our backend project evolves, the documentation needs to be updated accordingly, which can be quite cumbersome. Is there a better solution for this?

Of course, there is, and that solution is Swagger.

The main features of Swagger:

• Supports automatic and synchronized API documentation generation: With Swagger, you can directly generate documentation from your code, eliminating the need to manually write interface documentation. This is highly convenient for developers, saving time that can be better spent learning new technologies.
• Provides a web-based interface for testing APIs: Documentation alone is not enough. Swagger-generated documentation also supports online testing. With predefined parameters and formats, you can test APIs directly by entering parameter values in the provided interface.

By integrating with the Spring framework (via SpringDoc, official website: https://springdoc.org/), Swagger can effortlessly generate online documentation through annotations and scanning mechanisms. Once the project is running, frontend developers can access the Swagger-generated frontend page to view and test APIs.

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.1.0</version>
</dependency>

Once the project is up and running, we can directly access: http://localhost:8080/swagger-ui/index.html to view our development documentation.

You can see that this development documentation automatically includes the interfaces we have defined, along with the corresponding entity classes listed below. This page is not just for displaying interfaces; it also allows you to directly debug them.

This is incredibly convenient—not only can frontend developers quickly look up the interface definitions, but we can also perform online interface testing ourselves, effectively eliminating the need for tools like Postman.

Although Swagger's UI already does an excellent job of displaying the backend-provided interface information, it can often appear cluttered. Let’s look at how to configure some descriptive information for the interfaces. First, we need to display some basic information about the documentation on the page. This can be easily achieved with just a single Bean:

@Bean
public OpenAPI springDocOpenAPI() {
    return new OpenAPI().info(new Info()
            .title("Library Management System - Online API Documentation")  // Set the API documentation title
            .description("This is the backend API documentation for a Library Management System. Frontend developers are welcome to review it!")  // Provide an overview
            .version("2.0")  // Current API version
            .license(new License()
                    .name("My Bilibili Profile")  // Specify the license or use this field for other purposes
                    .url("https://space.bilibili.com/37737161")));  // Provide the URL for reference
}

This way, our page will display the customized textual information：

By doing this, we can provide detailed descriptions for both controllers and individual API endpoints in our Swagger documentation.

// Use @Tag to add a description for the Controller
@Tag(name = "Account Verification", description = "Includes operations such as user login, registration, and captcha requests.")
public class TestController {
    ...
}

You can add the @Tag annotation above the class name and provide relevant information to set a description for the current Controller. Next, we can configure descriptions for all request mappings:

@ApiResponses({
       @ApiResponse(responseCode = "200", description = "Test successful"),
       @ApiResponse(responseCode = "500", description = "Test failed")  // Description for different status codes
})
@Operation(summary = "Test endpoint for requesting user data")  // Functionality description of the endpoint
@ResponseBody
@GetMapping("/hello")
// Request parameter description and example
public String hello(@Parameter(description = "Test text data", example = "KFCvivo50") @RequestParam String text) {
    return "Hello World";
}

For those endpoints that do not need to be displayed in the documentation, we can simply ignore them:

@Hidden
@ResponseBody
@GetMapping("/hello")
public String hello() {
    return "Hello World";
}

For entity classes, we can also write corresponding API documentation:

@Data
@Schema(description = "User Information Entity")
public class User {
    @Schema(description = "User ID")
    int id;
    @Schema(description = "User Name")
    String name;
    @Schema(description = "User Email")
    String email;
    @Schema(description = "User Password")
    String password;
}

This way, we can view the entity class overview and the description of each attribute in the documentation.

However, this type of documentation is only suitable for development environments. For production environments, we need to disable the documentation:

springdoc:
  api-docs:
    enabled: false

With this configuration, the API documentation will be disabled in production.