Spring Boot 项目引入 Swagger3

前言

前后端分离的项目，接口文档的存在十分重要。与手动编写接口文档不同，swagger是一个自动生成接口文档的工具，在需求不断变更的开发环境下，手动编写文档的效率实在太低。与新版的swagger3相比swagger2配置更少，只需要简单操作如下。

1.项目引入Swagger

在项目的pom.xml插入Swaager3.0 的坐标

<!-- Swagger API文档 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

2.创建Swagger配置类

在项目创建一个配置类Swagger3Config.java

package cn.mooding.config;

import io.swagger.annotations.ApiOperation;
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.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

/**
 * @Author BlueFire
 * @email D102601560@gamil.com
 * @Date 2020/10/24 -14:30
 */
@Configuration
@EnableOpenApi
public class Swagger3Config {
    //可以配置在application文件中
    /**
     * 与Spring 同一级的配置
     *swagger:
     *   enable: true
     *   application-name: ${spring.application.name}
     *   application-version: 1.0
     *   application-description: springfox swagger 3.0整合Demo
     *   try-host: http://localhost:${server.port}
     */
    Boolean swaggerEnabled=true;//ture 启用Swagger3.0 fasle 禁用（生产环境要禁用）
    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                // 是否开启
                .enable(swaggerEnabled)
                .select()
                // 扫描的路径使用@Api的controller
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                // 指定路径处理PathSelectors.any()代表所有的路径
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("Swagger3接口文档")
                .description("适用于前后端分离统一的接口文档")
                //作者信息
                //.contact(new Contact("name","url", "email"))
                .contact(new Contact("木丁","www.mooding.cn", "D102601560@gamil.com"))
                .version("1.0")
                .build();
    }
}

3.创建一个测试Controller

package cn.mooding.system.modules.system.controller;


import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

/**
 * @Author BlueFire
 * @email D102601560@gamil.com
 * @Date 2020/10/24 -14:30
 */
@Api(tags = "测试接口无意义")
@RestController("/test")
public class HelloController {
    @Autowired
    private ISysJobService jobService;

    @GetMapping(value="/hello1")
    @ApiOperation("无参接口")
    public ResponseResult hello() throws SchedulerException {
        
        return "无参接口";
    }

    @ApiOperation(value = "有参数接口", notes = "")
    @GetMapping(value="/hello2")
    public Object hello( @ApiParam(value = "desc",required=true) @RequestParam String name) {
        return "有参数接口,name:" + name + "!";
    }

}

4.去除访问控制

如果项目中使用了shiro或者spring security权限控制需要将控制忽略如下的访问拦截

//Swagger -ui 过滤 shiro
filterChainDefinitionMap.put("/swagger-ui", "anon");
filterChainDefinitionMap.put("/swagger**/**", "anon");
filterChainDefinitionMap.put("/swagger-resources**/*", "anon");
filterChainDefinitionMap.put("/v3/api-docs", "anon");


//Swagger -ui 过滤 Spring security 
.antMatchers("/swagger**/**").anonymous()
.antMatchers("/swagger-resources**/*").anonymous()
.antMatchers("/v3/api-docs").anonymous()

5.访问Swagger页面

Swagger 3.0 访问地址http://localhost:8080/swagger-ui/ （不是http://localhost:8080/swagger-ui.html,这个是swagger 2.x的路径）

6.使用第三方UI

官方的页面比较繁琐可以使用第三方UI

在pom.xml文件中引入

<!-- 美化swagger 页面-->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.6</version>
</dependency>

此时的访问路径为 http://localhost:8080/doc.html，原来的路径也还可以访问