Swagger2集成

Swagger集成

Swagger官网

https://swagger.io/docs

依赖导入

<!-- Swagger2依赖 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

配置类编写

@Configuration
@EnableSwagger2  //启用Swagger
public class SwaggerConfig {
    //读取yaml配置，动态控制swagger是否启用
    @Value("${swagger.enable}")
    private boolean enable;
    @Bean
    public Docket createRestApi(){
        System.out.println(enable);
        return  new Docket(DocumentationType.SWAGGER_2)
                    //配置作者信息及标题的基本信息
                    .apiInfo(getApiInfo())
                    //控制是否启用
                    .enable(enable)
                    .select()
                    //扫描路径处理 any代表扫描所有，none代表全部不扫描
//                    .paths(PathSelectors.any())
                    //扫描所有
//                    .apis(RequestHandlerSelectors.any())
                    //指定包路径扫描
                    .apis(RequestHandlerSelectors.basePackage("com.lwp.study.controller"))
                    //指定类注解扫描
//                    .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
                    //指定方法注解扫描
//                    .apis(RequestHandlerSelectors.withMethodAnnotation(PostMapping.class))
                    .build()
                ;
    }
    private ApiInfo getApiInfo(){
        //作者信息
        Contact contact= new Contact("魔尊","https://www.cnblogs.com/mzstudy/","lwenpu@163.com");
        return new ApiInfo(
               "魔尊的测试",
               "只要学不死，就往死里学",
               "V1.0",
                "https://www.cnblogs.com/mzstudy/",
                contact,
                "Apache 2.0",
                "https://www.apache.org/licenses/LICENSE-2.0.html",
                new ArrayList<>()
       );
    }
}

启动成功访问

#只需要在端口号后面追加路由：/swagger-ui.html
例：http://127.0.0.1:18080/swagger-ui.html

分组配置

单个分组配置

@Bean
public Docket docket1(){
    return new Docket(DocumentationType.SWAGGER_2)
        .groupName("溪风的API");  //只需要添加该方法就可以
}

多个分组配置

//按各自需要配置Docket进行bean注入即可，可各自定制化swagger页面的所有信息，具体参考配置类编写的Docket
@Bean
public Docket docket1(){
    return new Docket(DocumentationType.SWAGGER_2)
        .groupName("溪风的API");
}

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

yaml多环境文件配置

主文件

#application.yml
spring:
  profiles:
    active: dev

开发环境时文件

#application-dev.yml
swagger:
  enable: true

生产环境时文件

#application-pro.yml
swagger:
  enable: false

常用注解解释

控制层常用注解：
    //用于类注解说明
    @Api(value="测试学生接口",tags = "学生相关接口")
    //用于方法参数说明，name参数名；value参数说明，备注；dataType参数类型；required 是否必传
    @ApiImplicitParam(name="student",value="学生对象",dataType = "Student",required = true)
    //用于方法注释
    @ApiOperation("添加学生")
    //用于参数说明，使用在参数前面
    @ApiParam("主键标识") 注：使用了@ApiImplicitParam无需使用该注解

注：当控制层的返回值存在实体类对象，swagger就会将对应的实体类扫描展示
实体类常用注解：
	//用于类说明
	@ApiModel("用户实体类")
	//用于字段说明
	@ApiModelProperty("名称") 
	注：如果参数类型非String，需要使用example指定默认值，否则会抛出异常
	例如：@ApiModelProperty(value = "性别{0代表男，1代表女}",example = "0")
	 	 private Integer stuSex;

代码实操

控制层

@RestController
@RequestMapping("/student")
//该类的接口说明
@Api(value="测试学生接口",tags = "学生相关接口")
public class StudentController {

    @Autowired
    private StudentMapper studentMapper;

    @GetMapping("/getStudentAll")
    @ApiOperation("查询所有学生信息")
    public List<Student> getStudentAll(){
        return studentMapper.getAllStudent();
    }

    @GetMapping("/addStudent")
    //方法参数说明，name参数名；value参数说明，备注；dataType参数类型；required 是否必传
    @ApiImplicitParam(name="student",value="学生对象",dataType = "Student",required = true)
    //方法注释
    @ApiOperation("添加学生")
    public List<Student> addStudent(Student student){
        student.setStuId(UUID.randomUUID().toString());
        studentMapper.addStudent(student);
        return studentMapper.getAllStudent();
    }


    @GetMapping("/updateStudent")
    @ApiImplicitParam(name="student",value="学生对象",dataType = "Student",required = true)
    @ApiOperation("修改学生信息")
    public List<Student> updateStudent(Student student){
        studentMapper.updateStudent(student);
        return studentMapper.getAllStudent();
    }

    @ApiImplicitParam(name="stuId",value="学生主键标识",dataType = "String",required = true)
    @ApiOperation("删除学生信息")
    @GetMapping("/delStudent")
    public List<Student> delStudent(@ApiParam("主键标识")String stuId){
        studentMapper.delStudent(stuId);
        return studentMapper.getAllStudent();
    }

}

实体类

@Data
@AllArgsConstructor
@NoArgsConstructor
@ApiModel("用户实体类")
public class Student {
    @ApiModelProperty("主键标识")
    private String stuId;
    @ApiModelProperty("名称")
    private String stuName;
    @ApiModelProperty(value = "性别{0代表男，1代表女}",example = "0")
    private Integer stuSex;
    @ApiModelProperty("地址")
    private String stuAddress;
    @ApiModelProperty(value = "年龄",example = "0")
    private Integer stuAge;
}

页面效果

集成Spring Security请求被拦截

@Override
public void configure(WebSecurity web) throws Exception {
    web.ignoring()
            .antMatchers("/swagger-ui.html")
            .antMatchers("/v2/**")
            .antMatchers("/swagger-resources/**");
}