SpringBoot集成Swagger（非常详细）

Swagger 是一系列用于 RESTful API 开发的工具。开源的部分包括：

• OpenAPI Specification：API 规范，规定了如何描述一个系统的 API；
• Swagger Codegen：用于通过 API 规范生成服务端和客户端代码；
• Swagger Editor：用来编写 API 规范；
• Swagger UI：用于展示 API 规范。

非开源的部分包括：

• Swagger Hub：云服务，相当于 Editor + Codegen + UI；
• Swagger Inspector：手动测试 API 的工具；
• SoapUI Pro：功能测试和安全测试的自动化工具；
• LoadUI Pro：压力测试和性能测试的自动化工具。

在微服务的盛行下，成千上万的接口文档编写不可能靠人力来编写，于是 Swagger 就产生了，它采用自动化实现并解决了人力编写接口文档的问题。它通过在接口及实体上添加几个注解的方式能够在项目启动后自动化生成接口文档。

Swagger 提供了一个全新的维护 API 文档的方式，有四大优点：

• 只需要少量的注解，Swagger 就可以根据代码自动生成API文档，很好地保证了文档的时效性；
• 跨语言性，支持 40 多种语言；
• Swagger UI 呈现出来的是一份可交互式的 API 文档，我们可以直接在文档页面尝试 API 的调用，省去了准备复杂的调用参数的过程；
• 可以将文档规范导入相关的工具（例如 SoapUI），这些工具将会为我们自动创建自动化测试。

【实例】 Spring Boot自动生成接口文档。
1) 在 pom.xml 中添加 Springfox 依赖包：

<!-- 引入 Springfox（swagger）支持包 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

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

在 application.yml 配置文件中添加 swagger 配置：

spring:
# 启用swagger支持
swagger2:
   enabled: true
#…

2) 新建 SwaggerConfig.java 配置类：

@Configuration
@EnableSwagger2
@EnableWebMvc
public class SwaggerConfig implements WebMvcConfigurer {

    private static final String BASE_PACKAGE = "com.example.shiro";

    @Value("${spring.swagger2.enabled}")
    private Boolean swaggerEnabled;

    @Override
    public void configureDefaultServletHandling(DefaultServletHandlerConfigurer configurer) {
        configurer.enable();
    }

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                // 设置是否启用
                .enable(swaggerEnabled)
                // 选择为哪些目标接口生成接口文档
                .select()
                // 设置需要生成接口文档的目录包
                .apis(RequestHandlerSelectors.basePackage(BASE_PACKAGE))
                // 任意路径
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 设置 ApiInfo
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Shiro-Demo 接口文档")
                .description("Spring Boot Shiro Demo")
                // 配置服务网站
                // .termsOfServiceUrl("")
                .version("v0.0.1")
                .build();
    }

    /**
     * 解决 swagger 被拦截的问题
     * @param registry
     */
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        // 解决静态资源无法访问的问题
        registry.addResourceHandler("/**")
                .addResourceLocations("classpath:/static/");
        // 解决 swagger-ui.html 无法访问的问题
        registry.addResourceHandler("/swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        // 解决 doc.html 无法访问的问题
        registry.addResourceHandler("/doc.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        // 解决 swagger 的 js 文件无法访问的问题
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

3) 修改 ShiroConfig.java 配置类，将 Shiro 对 Swagger 的权限放开：

@Bean
public ShiroFilterFactoryBean shiroFilterFactoryBean(SecurityManager securityManager) {
    ShiroFilterFactoryBean shiroFilterFactoryBean = new ShiroFilterFactoryBean();
    shiroFilterFactoryBean.setSecurityManager(securityManager);

    Map<String, String> map = new HashMap<>();

    // 登出
    map.put("/user/logout", "logout");
    // 放行 Swagger 相关资源
    map.put("/swagger-ui.html", "anon");
    map.put("/webjars/springfox-swagger-ui/**", "anon");
    map.put("/swagger-resources/**", "anon");
    map.put("/v2/api-docs", "anon");

    shiroFilterFactoryBean.setFilterChainDefinitionMap(map);
    return shiroFilterFactoryBean;
}

4) 接下来修改 UserRestController，编写符合 Swagger 规范的接口文档：

@RestController
@RequestMapping("/user")
@Api(tags = "用户管理")
public class UserRestController {
    @Resource
    private UserService userService;

    @ApiOperation(value = "用户注册", notes = "使用用户名和密码注册用户", httpMethod = "POST")
    @ApiImplicitParams({
        @ApiImplicitParam(name = "username", value = "用户名", required = true, dataTypeClass = String.class),
        @ApiImplicitParam(name = "password", value = "密码", required = true, dataTypeClass = String.class)
    })
    @ApiResponses({
        @ApiResponse(code = 1, message = "success", response = JsonResult.class),
        @ApiResponse(code = -1, message = "error")
    })
    @RequiresGuest
    @PostMapping("/register")
    public JsonResult create(@RequestBody UserVo userVo) {
        // 方法体未在图片中展示
    }
}

编写完成后，编译运行项目，访问 http://localhost:8080/swagger-ui.html 就可以看到接口文档已经生成成功，如下图所示。