一、Swagger

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

功能主要包括以下几点：

A. 使得前后端分离开发更加方便，有利于团队协作

B. 接口文档在线自动生成，降低后端开发人员编写接口文档的负担

C. 接口功能测试

二、Swagger常用注解

1. 问题

如果不在controller方法或者类中声明具体含义，那么在访问接口文档的时候，接口分类和接口描述都是Controller的类名和方法名，可读性很差，所以需要通过注解标注方法或者类的具体含义，重启项目后，就可以提高接口文档的可读性了。

2. 注解

注解	位置	说明
@Api	类	加载Controller类上,表示对类的说明
@ApiModel	类(通常是实体类)	描述实体类的作用
@ApiModelProperty	属性	描述实体类的属性
@ApiOperation	方法	说明方法的用途、作用
@ApiImplicitParams	方法	表示一组参数说明
@ApiImplicitParam	方法	用在@ApiImplicitParams注解中，指定一个请求参数的各个方面的属性


1. 通过 @ApiModel , @ApiModelProperty 来描述实体类及属性

比如：
@ApiModel("返回结果")
public class R<T> implements Serializable{
        @ApiModelProperty("编码")
        private Integer code; //编码：1成功，0和其它数字为失败
        ...
}

2.通过注解： @Api， @APIOperation， @ApiImplicitParams, @ApiImplicitParam描述Controller、方法及其方法参数

比如：
@RestController
@RequestMapping("/setmeal")
@Slf4j
@Api(tags = "xxx相关接口")
public class SetmealController {

    @PostMapping
    @ApiOperation(value = "新增接口")
    public R<String> save(@RequestBody SetmealDto setmealDto){
        ...
        return R.success("新增成功");
    }
    
    @GetMapping("/page")
    @ApiOperation(value = "xxx分页查询接口")
    @ApiImplicitParams({
        @ApiImplicitParam(name = "page",value = "页码",required = true),
        @ApiImplicitParam(name = "pageSize",value = "每页记录数",required = true),
        @ApiImplicitParam(name = "name",value = "条件名称",required = false)
    })
        public R<Page> page(int page,int pageSize,String name){
        ...
        return R.success(dtoPage);
    }
    
注意：@ApiImplicitParams, @ApiImplicitParam注解一般配合使用

三、使用knife4j实现MVC框架集成Swaager

knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案。

1.引入依赖

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>3.0.2</version>
</dependency>

2.导入knife4j相关配置类

@Slf4j
@Configuration
@EnableSwagger2
@EnableKnife4j
public class WebMvcConfig extends WebMvcConfigurationSupport {
	
    /**
     * 设置静态资源映射
     * @param registry
     */
    @Override
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        log.info("开始进行静态资源映射...");
        registry.addResourceHandler("/backend/**").addResourceLocations("classpath:/backend/");
        registry.addResourceHandler("/front/**").addResourceLocations("classpath:/front/");
    }
	
    /**
     * 扩展mvc框架的消息转换器
     * @param converters
     */
    @Override
    protected void extendMessageConverters(List<HttpMessageConverter<?>> converters) {
        log.info("扩展消息转换器...");
        //创建消息转换器对象
        MappingJackson2HttpMessageConverter messageConverter = new MappingJackson2HttpMessageConverter();
        //设置对象转换器，底层使用Jackson将Java对象转为json
        messageConverter.setObjectMapper(new JacksonObjectMapper());
        //将上面的消息转换器对象追加到mvc框架的转换器集合中
        converters.add(0,messageConverter);
    }
	
    @Bean
    public Docket createRestApi() {
        // 文档类型
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.maple.bilibili.controller"))
                .paths(PathSelectors.any())
                .build();
    }
	
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("bilibili")
                .version("1.0")
                .description("bilibili接口文档")
                .build();
    }
}


在生成Docket对象方法中，有一个扫描包的路径，该路径就是controller所在包的路径，Swagger在生成接口文档时，会扫描controller包下的注解，根据对应的注解生成接口文档。

3.设置静态资源映射

用于在Springboot项目中，默认静态资源的存放目录为 : 
"classpath:/resources/"
"classpath:/static/" 
"classpath:/public/" 

而在我们的项目中Swagger静态资源不在默认静态资源目录中, 
那么这个时候要想通过路径访问到Swagger静态资源, 就需要设置静态资源映射

由于swagger文档的生成，涉及到静态资源，需要进行静态资源映射，否则接口文档不能正常访问，所以需要在WebMvcConfig类中的addResourceHandlers方法中增加如下配置。

registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");

4.在LoginCheckFilter中设置不需要处理的请求路径

将Swagger及Knife4j相关的静态资源直接放行，无需登录即可访问，否则我们就需要登录之后，才可以访问接口文档的页面。

在原有的不需要处理的请求路径中，再增加如下链接：

"/doc.html",
"/webjars/**",
"/swagger-resources",
"/v2/api-docs"

5.查看接口文档

重新启动项目，访问接口文档，访问链接为： http://localhost:8080/doc.html

注意： 由于我们服务端的Controller中的业务增删改查的方法，都是必须登录之后才可以访问的，
所以，我们在测试时候，也是需要先访问登录接口。登录完成之后，我们可以再访问其他接口进行测试。

SpringBoot整合Swagger