Swagger简介

前后端分离开发模式中，api文档是最好的沟通方式。 Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful风格的 Web 服务从而无需使用对应后端接口的web前端进行测试实现前后端分离。

1. 及时性 (接口变更后，能够及时准确地通知相关前后端开发人员)
2. 规范性 (并且保证接口的规范性，如接口的地址，请求方式，参数及响应格式和错误信息)
3. 一致性 (接口信息一致，不会出现因开发人员拿到的文档版本不一致，而出现分歧)
4. 可测性 (直接在接口文档上进行测试，以方便理解业务)

swagger配置完成后访问：http://localhost:端口号/swagger-ui.html就能查看以下界面了。
swagger就是模拟配置前端url的需求来测试后端接口的功能，简化了前端url测试后端接口的流程可以通过swagger可视化传参直接进行测试和返回结果分析。
端口号可以通过.aproperties全局文件进行配置
图示：

只有将接口函数添加注解@ApiOperation才可以生成文档进行测试。
Spring Boot中使用Swagger2构建强大的RESTful API文档
@ApiOperation注解说明
总结：就是无需人为配置url进行对应接口函数的测试了，只需要对照文档要求填空就行了，并且swagger还将return值进行了专业分析。

配置方式

简单来说：

• 导入swagger插件
• 创建swagger的配置类
• 定义接口说明和参数说明

定义在类上： @Api
定义在方法上： @ApiOperation
定义在参数上： @ApiParam

若不创建swagger的配置类只是将swagger导入。

Springboot导入swagger插件和创建swagger配置类

需要学习maven的前导方法
maven笔记
maven管理多模块应用笔记
项目实例：

• 创建一个common子工程用于配置类，这样就可以通过maven引用工程依赖进行功能的实现了。

swagger插件

<!--swagger-->
 <dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.2.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.2.2</version>
</dependency>

配置类

package com.qlugcl.servicebase;

import com.google.common.base.Predicates;
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.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration//配置类
@EnableSwagger2 //swagger注解
public class SwaggerConfig {

    @Bean
    public Docket webApiConfig(){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("webApi")
                .apiInfo(webApiInfo())
                .select()
                .paths(Predicates.not(PathSelectors.regex("/admin/.*")))
                .paths(Predicates.not(PathSelectors.regex("/error.*")))
                .build();

    }

    private ApiInfo webApiInfo(){

        return new ApiInfoBuilder()
                .title("网站-课程中心API文档")
                .description("本文档描述了课程中心微服务接口定义")
                .version("1.0")
                .contact(new Contact("java", "http://atguigu.com", "1123@qq.com"))
                .build();
    }
}

• 运用maven将配置类所在子工程，视为依赖引用进来，提供跨工程使用配置类条件，然后经过一波继承操作这样，service_edu就成功装备上swagger插件和配置类了。

• 启动swagger配置类（@ComponentScan）

因为是跨工程引用且（@Configuration//配置类）只能在工程加载的时候自动运行而非实例化使用，所以需要扫描后触发（@Configuration//配置类）新建运行bean中方法从而进行swagger配置，若不主动扫描则无法新建bean并触发配置类中方法。

package com.qlugcl.eduservice;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.ComponentScan;

//启动类，用于启动该项目的springboot框架从而运行项目
@SpringBootApplication
//用于配置，要用到的配置类路径。com.qlugcl.servicebase中的SwaggerConfig
@ComponentScan(basePackages = "com.qlugcl")//扫描该项目和maven引入工程的com.qlugcl包，否则该启动类只扫描该对应当前项目的包
public class EduServiceApplication {
    public static void main(String[] args) {
        SpringApplication.run(EduServiceApplication.class,args);
    }
}

启动类位置注意事项

• AppApplication 一定要在包的最外层，否则Spring无法对所有的类进行托管，会造成@Autowired 无法注入。
• 这是因为SpringBoot项目的Bean装配默认规则是根据AppApplication
  类所在的包位置从上往下扫描！即只会扫描AppApplication 所在的包及其子包，其他包路径不会被扫描！！！
• 若想扫描其他包中配置类需要配置@ComponentScan。

总结

计算机开发的本质就是将重复性且具备普适性操作封装再使用。