swagger2 与 springmvc 整合 生成接口文档

简介

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

 我们的RESTful API就有可能要面对多个开发人员或多个开发团队：IOS开发、Android开发或是Web开发等。为了减少与其他团队平时开发期间的频繁沟通成本，传统做法我们会创建一份RESTful API文档来记录所有接口细节，然而这样的做法有以下几个问题：

  由于接口众多，并且细节复杂（需要考虑不同的HTTP请求类型、HTTP头部信息、HTTP请求内容等），高质量地创建这份文档本身就是件非常吃力的事，下游的抱怨声不绝于耳。
  随着时间推移，不断修改接口实现的时候都必须同步修改接口文档，而文档与代码又处于两个不同的媒介，除非有严格的管理机制，不然很容易导致不一致现象。
 为了解决上面这样的问题，本文将介绍RESTful API的重磅好伙伴Swagger2，它可以轻松的整合到Spring Boot中，并与Spring MVC程序配合组织出强大RESTful API文档。它既可以减少我们创建文档的工作量，同时说明内容又整合入实现代码中，让维护文档和修改代码整合为一体，可以让我们在修改代码逻辑的同时方便的修改文档说明。另外Swagger2也提供了强大的页面测试功能来调试每个RESTful API。具体效果如下图所示：

添加Swagger2依赖

在pom.xml中加入Swagger2的依赖

<dependency>  
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.4.0</version>
</dependency>  
<dependency>  
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.4.0</version>
</dependency>
    <dependency>
        <groupId>org.springframework</groupId>
        <artifactId>spring-context</artifactId>
        <version>4.3.4.RELEASE</version>
    </dependency>

或者
直接导入包

注意：Spring 必须 4 以上
Jackson最好2.8

创建Swagger2配置类：

/**   
 * Swagger2构建RESTful APIs  
 * @author AndyBao  
 * @version 4.0, 2016年12月20日 下午2:00:30   
 */   
@Configuration
@EnableWebMvc
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.ybt.web.app"))
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("APP RESTful APIs")
                .description("在线文档：http://www.xxx.xxx")
                .termsOfServiceUrl("http://www.xxxx.com.cn/")
                .contact("AndyBao")
                .version("0.5.1")
                .build();
    }

}

如上代码所示，通过@Configuration注解，让Spring来加载该类配置。再通过@EnableSwagger2注解来启用Swagger2。

再通过createRestApi函数创建Docket的Bean之后，apiInfo()用来创建该Api的基本信息（这些基本信息会展现在文档页面中）。select()函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现，本例采用指定扫描的包路径来定义，Swagger会扫描该包下所有Controller定义的API，并产生文档内容（除了被@ApiIgnore指定的请求）。

添加文档内容

给Controller 添加注解
通过@ApiOperation注解来给API增加说明、通过@ApiImplicitParams、@ApiImplicitParam注解来给参数增加说明。

    /**
     * 参数描述
     *
     * @param userName
     * @return
     */
    @RequestMapping(value = "/demo2/{userName}", method = RequestMethod.POST)
    @ApiOperation(value = "测试接口2", notes = "参数描述", code = 200, produces = "application/json")
    public ModelMap getDemo2(@ApiParam(name = "userName", value = "编号", required = true) @PathVariable("userName") String userName) {
        ModelMap map = new ModelMap();
        map.addAttribute("userName", userName);
        return map;
    }

重启web服务访问：

Swagger ui 已经通过jar包导进来了所以直接访问
http://localhost:8080/SunnyApp/swagger-ui.html
即可
或者把Swagger ui 静态文件 放到自己喜欢的目录
在GitHub上下载SwaggerUI项目（https://github.com/swagger-api/swagger-ui），将dist下所有内容拷贝到本地项目/apidoc下面，结果目录如下图所示：

打开目录下的index.html文件，找到代码片段url = “http://petstore.swagger.io/v2/swagger.json“;修改为“/apidoc/v2/api-docs”。