Spring boot集成Swagger2详解

1.    Swagger的产生

我们的RESTful API需要面对多个开发人员或多个开发团队:IOC开发,A’n’d’roid开发或是web开发等。为了减少与其它团队平时开发期间的频繁沟通成本,传统的做法我们回创建一份RESTful API文档来记录所有接口的细节,然后这样的做法会有以下几个问题:
由于接口众多,并且细节繁锁(需要考虑不同的HTTP请求类型,HTTP头部信息,HTTP请求内容等),高质量地创建这份文档本身就是件非常吃力的事,下游的抱怨声不绝于耳。
随着时间的转移,不断修改接口实现的时候都必须同步修改接口文档,而文档与代码又处于两个不同的媒介,除非有严格的管理机制,不然很容易导致不一致的对象
Swagger的产生就是为了解决以上这些问题

2.    Swagger介绍

Swagger是一个规范和完整性的框架,用于生成,描述,调用和可视化RESTful 风格的web服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步。Swagger让部署管理和使用功能强大的API从未如此简单

3.    在pom.xml添加依赖

<!-- swagger依赖 -->
<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>

4.    创建swagger的配置类

/**
 * Swagger配置类:
 * @version v.0.1
 * @date 2016年9月7日
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    /**
     * 可以定义多个组,比如本类中定义把test和demo区分开了
     * (访问页面就可以看到效果了)
     *
     */
   
    @SuppressWarnings("unchecked")
    @Bean
    public Docket testApi(){
       Docket docket = new Docket(DocumentationType.SWAGGER_2)
              .groupName("test")
              .genericModelSubstitutes(DeferredResult.class)
              .useDefaultResponseMessages(false)
                .forCodeGeneration(true)
                .pathMapping("/")// base,最终调用接口后会和paths拼接在一起
                .select()
                .paths(Predicates.or(PathSelectors.regex("/api/.*")))//过滤的接口
                .build()
                .apiInfo(testApiInfo());
              ;
       return docket;
    }
   
    @SuppressWarnings("unchecked")
    @Bean
    public Docket demoApi() {
        returnnew Docket(DocumentationType.SWAGGER_2)
                .groupName("demo")
                .genericModelSubstitutes(DeferredResult.class)
//              .genericModelSubstitutes(ResponseEntity.class)
                .useDefaultResponseMessages(false)
                .forCodeGeneration(false)
                .pathMapping("/")
                .select()
                .paths(Predicates.or(PathSelectors.regex("/demo/.*")))//过滤的接口
                .build()
                .apiInfo(demoApiInfo());
    }
   
     private ApiInfo testApiInfo() {
            ApiInfo apiInfo = new ApiInfo("Test相关接口",//大标题
                    "Test相关接口,主要用于测试.",//小标题
                    "1.0",//版本
                    "http://api.everycoding.com/",
                    "author",//作者
                    "云码网",//链接显示文字
                    "http://www.everycoding.com/"//网站链接
            );
 
            return apiInfo;
        }
 
        private ApiInfo demoApiInfo() {
            ApiInfo apiInfo = new ApiInfo("Demo相关接口",//大标题
                    "Demo相关接口,获取个数,获取列表,注意:",//小标题
                    "1.0",//版本
                    "http://api.everycoding.com/",
                    "author",//作者
                    "云码网",//链接显示文字
                    "http://www.everycoding.com/"//网站链接
            );
 
            returnapiInfo;
        }
   
}

上述代码所示,通过@Configruation注解,让spring来加载该类的配置,在通过@EnableSwagger2注解来启用swagger2.
再通过createRestApi函数创建Dock的bean之后,apiInfo()用来创建该Api的基本信息(这些基本信息会展现    在文档页面中)。Select()函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给swagger展现
经过这两步部署,我们启动服务后,访问就完成了集成

5.    测试
/**
 * Swagger2默认将所有的Controller中的RequestMapping方法都会暴露,然而在实际开发中,我们并不一定需要把所有API都提现在文档中查看,这种情况下,使用注解@ApiIgnore来解决,如果应用在Controller范围上,则当前Controller中的所有方法都会被忽略,如果应用在方法上,则对应用的方法忽略暴露API。
 
注解@ApiOperation和@ApiParam可以理解为API说明,多动手尝试就很容易理解了。
如果我们不使用这样注解进行说明,Swagger2也是有默认值的,没什么可说的试试就知道了。
 
在 http://localhost:8080/swagger-ui.html 显示页面的右上角有api_key ,springfox-swagger 2.2.2 版本并没有进行处理,我们可以自己添加拦截器拦截 /v2/api-docs来处理我们API文档的访问权限,如果要更严格更灵活的控制,可能需要修改源码来实现了。相信 springfox-swagger 的后期版本应该会支持更全面的应用需求的。
 */



评论

*
*