SpringBoot-整合Swagger

Swagger

• 号称世界上最流行的API框架

• Restful Api 文档在线自动生成器 => API 文档 与API 定义同步更新

• 直接运行，在线测试API

• 支持多种语言 （如：Java，PHP等）

• 官网：https://swagger.io/

1.导入maven依赖

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger2</artifactId>
   <version>2.9.2</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger-ui</artifactId>
   <version>2.9.2</version>
</dependency>

2.编写Swagger配置类

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    
}

访问测试 ：http://localhost:8080/swagger-ui.html ，可以看到swagger的界面；

扩展： 推荐不要用过高的swagger版本，会出现兼容性问题，如果这里出现空指针问题可以把Springboot版本降到2.5.5或者在yaml里面添加配置

spring:
  mvc:
     pathmatch:
          matching-strategy: ant_path_matcher

3.Swagger配置

基本配置

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

import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import javax.servlet.http.HttpSession;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean  //配置docket以配置Swagger具体参数
    public Docket productDocket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .enable(true)//配置是否启用Swagger，如果是false，在浏览器将无法访问
                .pathMapping("/")
                .select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
                //配置需要扫描的包
                .apis(RequestHandlerSelectors.basePackage("com.wjc.controller"))
                //配置扫描的路径，我设置为所有的路径
                .paths(PathSelectors.any())
                .build()
                .ignoredParameterTypes(HttpSession.class,HttpServletRequest.class,HttpServletResponse.class)  //忽略参数
                .apiInfo(apiInfo());   //关联上apiInfo()
    }
    public ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("接口文档")  //标题
                .description("测试接口文档")  //描述
                .version("1.0").build();
    }
 
}

4.Swagger分组

要分组开发，就写多个Docket，可以在每个Docket里面扫描不同的包，实现分工

 @Bean
    public  Docket docket1(){
        return  new Docket(DocumentationType.SWAGGER_2).groupName("A");
    }

    @Bean
    public  Docket docket2(){
        return  new Docket(DocumentationType.SWAGGER_2).groupName("B");
    }

5.Swagger常用注解

实体类注解

@ApiModel(value = "")  //用在类上

@ApiModelProperty("")    //用在属性上

@Data
@AllArgsConstructor
@NoArgsConstructor
@ApiModel(value = "测试实体类")
public class Dept {
    @ApiModelProperty("部门id")
    private  Integer deptno;
    @ApiModelProperty("部门姓名")
    private  String dname;
    @ApiModelProperty("部门职责")
    private  String db_source;
}

改注解修改的是Swagger Models里的注释

Controller类注解

@Api(tags = "")  //类注释

 @ApiOperation(value = "")   //方法注释

@RestController
@Api(tags = "部门控制类")
public class DeptController {
    @Resource
    private DeptMapper deptMapper;


    @ApiOperation(value = "查询全部")
    @GetMapping("/queryDeptList")
    public List<Dept> queryDeptList(){
        List<Dept> depts = deptMapper.queryDeptList();
        for (Dept dept : depts) {
            System.out.println(dept);
        }
        return  depts;
    }
    
}

扩展：如果觉得它原生的页面不好看的话，可以换皮肤哦

导入包

<!-- 引入swagger-bootstrap-ui包 /doc.html-->
<dependency>
   <groupId>com.github.xiaoymin</groupId>
   <artifactId>swagger-bootstrap-ui</artifactId>
   <version>1.9.1</version>
</dependency>

访问 http://localhost:8080/doc.html

免费资源，整合手册链接：SpringBoot集成Swagger2展现在线接口文档-Java文档类资源-CSDN下载