1. Swagger简介

1.1. 简介

swagger是一个流行的API开发框架，对整个API的开发周期都提供了相应的解决方案，比如API在线编辑器，API UI展示界面，代码生成器等诸多功能。

swagger框架以“开放API声明”（OpenAPI Specification，OAS）为基础，OAS本身是一个API规范，它用于描述一整套API接口，包括一个接口是GET还是POST请求，有哪些参数哪些header，都会被包括在这个文件中。

1.2. 和springfox的关系

如果想引入swagger进行API管理。目前 springfox 是一个很好的选择，它内部会自动解析Spring容器中Controller暴露出的接口，并且也提供了一个界面用于展示或调用这些API。

springfox的前身是swagger-springmvc，用于springmvc与swagger的整合。

2. 添加依赖

<dependency>
    <groupId>io.swagger.core.v3</groupId>
    <artifactId>swagger-annotations</artifactId>
    <version>2.1.7</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>3.0.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>3.0.0</version>
</dependency>

3. swagger配置类

3.1. 配置代码

@Configuration
@EnableSwagger2
@PropertySource("classpath:swagger.properties")
public class SwaggerConfig {

    @Bean
    public Docket docket() {

        return new Docket(DocumentationType.SWAGGER_2)
                .genericModelSubstitutes(DeferredResult.class)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.wanmait.esrestdemo.controller"))
                .paths(PathSelectors.any())
                //.paths(PathSelectors.ant("/q/**"))
                //.paths(PathSelectors.regex("(/q/|/qt/).*"))
                //.paths(PathSelectors.none())//生产环境设为全部路径都不符合条件，达到禁用swagger的目的
                .build()
                .apiInfo(apiInfo());
    }

    //自定义API文档基本信息，会展示在文档UI的头部
    private ApiInfo apiInfo() {
        Contact contact = new Contact("孙明","http://www.wanmait.com","62999860@qq.com");
        return new ApiInfoBuilder().title("万码学堂")
                .description("万码学堂企业管理系统")
                .contact(contact)
                .termsOfServiceUrl("http://www.wanmait.com")
                .version("1.0")
                .license("版权归万码学堂所有")
                .licenseUrl("http://www.wanmait.com")
                .build();
    }
}

3.2. 配置说明

select()用来初始化并返回一个API选择构造器

paths()设置路径筛选

apis()添加路径筛选条件

build()构建

3.2.1. PathSelectors说明

PathSelectors扫描匹配成功的路径，生成API，可用的 mapperHandler 路径匹配的方法： any()：匹配所有的路径；

ant()：匹配传入参数的路径，使用ant风格；

regex()：通过正则表达式匹配路径，多个路径中间使用或者|；

none()：所有路径都不满足条件，生产环境下可以用来屏蔽swagger。

3.2.2. RequestHandlerSelectors 说明

RequestHandlerSelectors 可使用的扫描条件：

basePackage()：只扫描指定包下的类；

any()：扫描所有类；

withClassAnnotation()：只扫描类上有某个的注解的类；

withMethodAnnotation()：只扫描方法上有某个注解的方法。

4. swagger.properties

在resources下新建swagger.properties文件，其中的内容为

springfox.documentation.swagger.v2.path=/swagger

5. 配置资源映射路径

@Configuration
public class WebConfig implements WebMvcConfigurer {
    //swagger的url映射
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/swagger/**").addResourceLocations("classpath:/swagger/dist/");
    }
}

6. swagger-ui

6.1. 下载并解压拷贝

下载swagger-ui，下载路径：

https://github.com/swagger-api/swagger-ui

将其中的dist文件夹拷贝到项目中的resources/swagger目录下

6.2. 修改index.html

修改dist目录下面的index.html，把url路径修改为和swagger.properties配置文件中配置的路径一致。

  <script>
  window.onload = function() {
    // Begin Swagger UI call region
    const ui = SwaggerUIBundle({
      //url: "https://petstore.swagger.io/v2/swagger.json",
      //项目的swagger访问路径
      url: "/swagger",
      dom_id: '#swagger-ui',
      deepLinking: true,
      presets: [
        SwaggerUIBundle.presets.apis,
        SwaggerUIStandalonePreset
      ],
      plugins: [
        SwaggerUIBundle.plugins.DownloadUrl
      ],
      layout: "StandaloneLayout"
    });
    // End Swagger UI call region

    window.ui = ui;
  };
script>