springboot整合swagger配置接口文档

springboot配置swagger接口文档

1 引入依赖

 springboot需要2.6.0以上
 
       <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>
        <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.6</version>
      </dependency>

2，配置文件添加

spring.mvc.pathmatch.matching-strategy=ant_path_matcher

3，添加配置类

package com.example.demo.config;


import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;
import java.util.List;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    //配置了swagger的Docket的bean实例
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());
    }

    //配置Swagger信息=apiInfo
    private ApiInfo apiInfo() {
        //作者信息
        Contact contact = new Contact("Elmar", "", "290793761@qq.com");
        return new ApiInfo("Elmar的接口文档", "世间永无bug", "v1.0", "", contact, "Apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList());
    }
}

package com.example.demo.config;

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;



@Configuration
public class WebMvcConfig implements WebMvcConfigurer {

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
        registry.addResourceHandler("doc.html")
                .addResourceLocations("classpath:/META-INF/resources/");
    }
}

4.接口添加注解

@Api：描述API接口的基本信息，包括接口名称、描述、作者等。
@ApiOperation：描述API接口的操作方法，包括HTTP请求方法、接口路径、接口说明等。
@ApiParam：描述API接口的参数信息，包括参数名称、参数类型、参数说明等。
@ApiModel：描述API接口的返回结果类型，包括返回结果的数据结构、返回结果的说明等。
@ApiModelProperty：描述API接口返回结果的属性信息，包括属性名称、属性类型、属性说明等。

@Api(value = "UserController", description = "用户管理接口", tags = {"用户管理"})
@RestController
@RequestMapping("/user")
public class UserController {
    @ApiOperation(value = "获取用户列表", notes = "获取所有用户列表")
    @GetMapping("/list")
    public List<User> getUserList() {
        // ...
    }
    
    @ApiOperation(value = "根据ID获取用户信息", notes = "根据ID获取用户信息")
    @GetMapping("/get")
    public User getUserById(@ApiParam(name = "id", value = "用户ID", required = true) @RequestParam Long id) {
        // ...
    }
    
    @ApiOperation(value = "添加用户", notes = "添加用户")
    @PostMapping("/add")
    public void addUser(@ApiParam(name = "user", value = "用户信息", required = true) @RequestBody User user) {
        // ...
    }
    
    @ApiOperation(value = "更新用户信息", notes = "更新用户信息")
    @PutMapping("/update")
    public void updateUser(@ApiParam(name = "user", value = "用户信息", required = true) @RequestBody User user) {
        // ...
    }
    
    @ApiOperation(value = "删除用户", notes = "删除用户")
    @DeleteMapping("/delete")
    public void deleteUser(@ApiParam(name = "id", value = "用户ID", required = true) @RequestParam Long id) {
        // ...
    }
}
 
@ApiModel(value = "User", description = "用户信息")
public class User {
    @ApiModelProperty(value = "用户ID")
    private Long id;
    
    @ApiModelProperty(value = "用户名")
    private String username;
    
    @ApiModelProperty(value = "用户密码")
    private String password;
    
    // ...
}

在上面的示例中，我们使用了@Api、@ApiOperation、@ApiParam、@ApiModel和@ApiModelProperty注解来描述API接口和参数，从而生成规范的API文档。