项目优化Day3-04-Swagger-介绍&使用方式&查看接口文档

项目优化Day3-04-Swagger-介绍&使用方式&查看接口文

Swagger：
Swagger是我们在进行前后端分离开发的时候，后端人员经常使用到的技术，使用这个Swagger就可以帮助我们来生成相应的接口文档，并且通过我们生成的
接口文档还可以来做测试。

1.介绍：
使用Swagger你只需要按照他的规范去定义接口以及接口相关的信息，再通过Swagger衍生出来的一系列项目和工具，就可以做到生成各种格式的接口文档，
以及在线接口调试页面等等。
官网：https://swagger.io/

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

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

操作步骤：
1.导入knife4j的Maven坐标

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

​ 2、导入knife4j相关配置类（WebMvcConfig）

@Slf4j
@Configuration
@EnableSwagger2
@EnableKnife4j
public class WebMveConfig extends WebMvcConfigurationSupport {

    /*设置静态资源映射*/
    @Override
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        log.info("开始静态资源映射...");
        registry.addResourceHandler("/backend/**").addResourceLocations("classpath:/backend/");
        registry.addResourceHandler("/front/**").addResourceLocations("classpath:/front/");
    }


    /*扩展mvc框架的消息转换器*/
    //这个方法是什么时候调用？？
    //这个类当前在Mvc配置类里面，这个方法是我们项目启动的时候就会调用，然后他就会把我们自己new出来的这个转换器放到
    //converters这个集合中，当我们的方法执行到这儿的时候，其实这个集合里面已经放了其中的几个转换器了，是mvc框架默认的几个转换器。
    //然后我们在这儿又给他追加了一个，并且把他放在最前的位置，这样我们在使用的时候，就会先试用我们自己new出来的这个转换器。
    @Override
    protected void extendMessageConverters(List<HttpMessageConverter<?>> converters) {
        log.info("扩展消息转换器");
        //创建消息转换器对象
        //这个消息转换器的作用就是：将我们Controller这个方法的返回结果，这里拿分页查询返回结果来说，最终返回的是一个R对象，
        //把这个结果转成相应的json，然后再通过输出流的方式响应给我们的页面，所以我们页面上看到的就是相应的json数据。
        //这些数据怎么来的？？其实就是通过我们这个转换器，把它转换成json的。
        MappingJackson2HttpMessageConverter messageConverter = new MappingJackson2HttpMessageConverter();

        //现在我们就需要来扩展自己的一个新的转换器，然后他在转换的过程当中，需要把我们的结果R对象转成json，转json的过程他会使用到一个对象转换器，
        //其实底层就是使用我们的这个Jackson，刚才已经把这个类拷贝进去了，现在我们需要来设置我们的对象转换器。底层使用Jackson将我们的Java对象
        //转为json
        messageConverter.setObjectMapper(new JacksonObjectMapper());

        //将我们上面的消息转换器对象追加到我们mvc框架的转换器集合中(就是形参converters，是一个集合)，
        //在追加的时候记得加上索引，因为这个转换器是有顺序的，我们需要让我们自己的转换器在最前面，也就是下标为0的位置。
        //这样的话就会优先使用我们自己的转换器
        converters.add(0, messageConverter);
    }

    //下面两个

    @Bean
    public Docket createRestApi() { 
        // 文档类型
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.itheima.reggie.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("瑞吉外卖")
                .version("1.0")
                .description("瑞吉外卖接口文档")
                .build();
    }

} 

​ 3.设置静态资源，否则接口文档页面无法访问
​ 设置静态资源映射(WebMvcConfig类中的addResourceHandlers方法)，否则接口文档页面无法访问

    /*设置静态资源映射*/
    @Override
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        log.info("开始静态资源映射...");
        registry.addResourceHandler("/backend/**").addResourceLocations("classpath:/backend/");
        registry.addResourceHandler("/front/**").addResourceLocations("classpath:/front/");
        //下面两行
        registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }

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

        //定义不需要处理的请求
        String[] urls = new String[]{
                "/employee/login",
                "/employee/logout",
                "/backend/**",
                "/front/**",
                "/common/**",
                "/user/sendMsg",//移动端发送短信
                "/user/login"//移动端登录,
                //下面四个
                "/doc.html",
                "/webjars/**",
                "/swagger-resources",
                "/v2/api-docs"
        };

如果不放行的话，就需要登陆了之后才能查看文档