Swagger 初体验

这世间 没有 不相交的平行线

前言

以前刚接触到 Swagger，不知道他还能导出成 Word、PDF 文档，就觉得 Postman+ 文档够用了，现在觉得代码中集成这样的框架，在初期能够方便很多。

• 功能丰富 ：支持多种注解，自动生成接口文档界面，支持在界面测试 API 接口功能；
• 条理清晰 ：开发过程中花一点写注释的时间，就可以及时的更新 API 文档，省心省力；
• 整合简单 ：通过添加 pom 依赖和简单配置，内嵌于应用中就可同时发布 API 接口文档界面，不需要部署独立服务。

Swagger 集成项目

Swagger 本身是一种规范，而 SpringFox-Swagger 是专注于 Spring 生态的实现，Spring-Swagger-UI 则是对 Swagger-UI 的封装。

代码整整合也非常的简单，首先是 pom 引入：

pom 引入

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.6.1</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.6.1</version>
        </dependency>
        <dependency>
            <groupId>io.github.swagger2markup</groupId>
            <artifactId>swagger2markup</artifactId>
            <version>1.3.1</version>
        </dependency>

其中 swagger2markup 是用于 Swagger 导出 PDF/HTML 的依赖，离线文档之后再更新，目前还有点问题。

在 application.properties 中加这么一句 spring.resources.static-locations=classpath:/static/ ，不然 swagger-ui.html 这个页面会被拦截。

Configuration 注入

/**
 * @ClassName SwaggerConfiguration
 * @Description TODO
 * @Author MatthewHan
 * @Date 2019/7/16 16:15
 * @Version 1.0
 **/
@Configuration
public class SwaggerConfiguration {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                // 这是注意的代码
                .apis(RequestHandlerSelectors.basePackage("com.zrtg.ldapsync.common.action"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("ldap-sync接口文档")
                .description("用于大院LDAP服务器同步无纸化办公组织架构")
                .termsOfServiceUrl("http://gitlab.zrtg.com/996team/ldap-sync")
                .version("1.0")
                .build();
    }

}

• 其中 basePackage 中的一般配置 controller 的路径， paths 属性进行过滤， apis 属性可以设置扫描包，或者通过注解的方式标识；通过 enable 属性，可以在 application-{profile}.properties 文件中设置相应值，主要用于控制生产环境不生成接口文档。另外还有 groupName() 进行分组，比如高级客户、~~低端人口（雾）~~之类的分组。
• apiInfo 中包装了文档的 title 、 description 、 version 这些信息。

然后在 SpringBoot 的入口类中加上 @EnableSwagger2 表示开启 Swagger2。

完成这些步骤后，发现其实访问 https://localhost/swagger-ui.html 并没有 swagger 页面，原因是在所映射的地址在 SpringBoot 静态资源文件夹下找不到。所以需要定义一个拦截器来放行。

实现 WebMvcConfigurer

/**
 * @ClassName WebMvcConfiguration
 * @Description 用于Swagger UI显示
 * @Author MatthewHan
 * @Date 2019/7/16 16:37
 * @Version 1.0
 **/
@Configuration
public class WebMvcConfiguration implements WebMvcConfigurer {

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {

        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
    
        registry.addResourceHandler("/templates/**")
                .addResourceLocations("classpath:/META-INF/resources/templates/");
    }
}

我们只需要重写 addResourceHandlers 方法即可，通过 addResourceHandler 添加映射路径，然后再通过 addResourceLocations 来指定路径。 addResourceLocations 指的是文件放置的目录， addResoureHandler 指的是对外暴露的访问路径。

在 controller 中集成注解

最后通过浏览器来访问 https://localhost/swagger-ui.html 如下图：

Method 类型、相关描述、Example、StatusCode 都会自动帮你生成。

小问题记录

注解问题

直接在通过 @PathVariable 注解的参数在 Swagger 中用了 @ApiImplicitParam ，发现在页面中请求是有问题的，这个注解应该对应的是 func(@Param("arg") String arg) 方法，实际上正确的用法是 @ApiParam 。类似下图代码：

/**
* 测试
* 用于添加一个ou，例如：department，employee
* @param ou
* @return
*/
    @ApiOperation(value = "添加一个OU")
    @ApiParam(name = "ou", value = "组织单元", required = true)
    @PostMapping("/add-ldap-ou/{ou}")
    public BaseResult<String> addLdapOu(@PathVariable("ou")String ou){
    ...
}

与 Shiro 集成的问题

通过无拦截测试总结了如下的资源路径是 swagger 在渲染页面时的必需。如果工程中包含了 Shiro 安全框架，需要对 swagger 进行放行。

// 设置拦截器
Map<String, String> filterChainDefinitionMap = new LinkedHashMap<>();
// swagger放行
filterChainDefinitionMap.put("/swagger-ui.html", "anon");
filterChainDefinitionMap.put("/swagger-resources/**", "anon");
filterChainDefinitionMap.put("/v2/**", "anon");
filterChainDefinitionMap.put("/webjars/**", "anon");
filterChainDefinitionMap.put("/configuration/**", "anon");

ShiroFilterFactoryBean shiroFilterFactoryBean = new ShiroFilterFactoryBean();
shiroFilterFactoryBean.setFilterChainDefinitionMap(filterChainDefinitionMap);

在你的 Shiro 配置类中添加如上路径即可。

离线文档（后续更新）