Detailed explanation of spring boot API document generation tool swagger configuration

Swagger is an API documentation generation tool that can help you quickly generate and view API documentation. In a Spring Boot project, you can use the springfox-swagger2 and springfox-swagger-ui libraries to integrate Swagger. Here are detailed instructions on how to configure Swagger in a Spring Boot project, along with an example:

1. Add dependencies

pom.xmlAdd springfox-swagger2 and springfox-swagger-ui dependencies in the file :

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

2. Create Swagger configuration class

Create a SwaggerConfigconfiguration class named and @EnableSwagger2enable Swagger support using the annotation:

import.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    
    

    @Bean
    public Docket api() {
    
    
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
    
    
        return new ApiInfoBuilder()
                .title("Spring Boot REST API")
                .description("Spring Boot REST API 示例")
                .version("1.0.0")
                .contact(new Contact("Your Name", "yourwebsite.com", "[email protected]"))
                .build();
    }
}

In this configuration class, we created a DocketBean to configure the generation rules of Swagger documents. We specified the basic information of the API documentation, such as title, description, version, and contact information. We also RequestHandlerSelectors.basePackagespecify the packages to be scanned through the method so that Swagger only generates API documents under the specified package.

3. Access Swagger UI

After starting the Spring Boot project, visit http://localhost:8080/swagger-ui.htmland you will see the Swagger UI page, which contains your API documentation.

4. Example

Suppose you have a UserControllercontroller class named as follows:

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/users")
@Api(tags = "用户管理")
public class UserController {
    
    

    @GetMapping
    @ApiOperation("获取所有用户")
    public List<User> getAllUsers() {
    
    
        // ...
    }

    @GetMapping("/{id}")
    @ApiOperation("根据 ID 获取用户")
    public User getUserById(@PathVariable("id") Long id) {
    
    
        // ...
    }
}

In this controller class, we use @Apithe and @ApiOperationannotations to provide Swagger with more information about the API. After starting the project, visit the Swagger UI page and you will see that this information is already included in the API documentation.

That’s it for detailed instructions and examples of configuring Swagger in a Spring Boot project. You can adjust Swagger configuration and annotations according to your needs.