Spring MVC集成Swagger

什么是Swagger?

　　大部分 Web 应用程序都支持 RESTful API，但不同于 SOAP API——REST API 依赖于 HTTP 方法，缺少与 Web 服务描述语言（Web Services Description Language，WSDL）类似的语言来定义使用者与提供者之间的请求和响应结构。由于没有充分的合同服务，许多 REST API 提供者使用 Microsoft Word 文档或维基页面来记录 API 用法。这些格式使协作和文档版本控制变得很困难，尤其对于有许多 API 或资源的应用程序，或者在 API 采用迭代式开发方式时。这些文档类型在集成到自动化测试应用程序中时变得更难。

　　Swagger是一个简单但功能强大的API表达工具。它具有地球上最大的API工具生态系统，数以千计的开发人员，使用几乎所有的现代编程语言，都在支持和使用Swagger。使用Swagger生成API，我们可以得到交互式文档，自动生成代码的SDK以及API的发现特性等。

　　开源Swagger框架帮助 API 使用者和开发人员纠正了这些问题。该框架为创建 JSON 或 YAML（JSON 的一个人性化的超集）格式的 RESTful API 文档提供了Open API（以前称为 Swagger 规范）。Swagger 文档可由各种编程语言处理，可在软件开发周期中签入源代码控制系统中，以便进行版本管理。

　　一句话，Swagger是一个让我们可以更方便、更好的设计和表达api的一个开源框架。

　　Ps:

什么是openapi? 

在互联网时代，把网站的服务封装成一系列计算机易识别的数据接口开放出去，供第三方开发者使用，这种行为就叫做开放网站的API，与之对应的，所开放的API就被称作openAPI。

如何使用Swagger：

　　本文，主要介绍Swagger和Spring MVC的集成使用(采用Maven管理jar包)，若您恰有此需求，请继续阅读。

　　首先，我们在pom.xml文件中添加如下：

<dependency>
           <groupId>com.mangofactory</groupId>
           <artifactId>swagger-springmvc</artifactId>
           <version>1.0.2</version>
       </dependency>
       <dependency>
           <groupId>com.google.guava</groupId>
           <artifactId>guava</artifactId>
           <version>15.0</version>
       </dependency>
       <dependency>
           <groupId>com.fasterxml.jackson.core</groupId>
           <artifactId>jackson-annotations</artifactId>
           <version>2.4.4</version>
       </dependency>
       <dependency>
           <groupId>com.fasterxml.jackson.core</groupId>
           <artifactId>jackson-databind</artifactId>
           <version>2.4.4</version>
       </dependency>
       <dependency>
           <groupId>com.fasterxml.jackson.core</groupId>
           <artifactId>jackson-core</artifactId>
           <version>2.4.4</version>
       </dependency>

由于Swagger获取api后是以json形式返回数据给Swagger ui，所以这里需要引入jackson的相关包

　　然后，建包config，在包下新建配置类SwaggerConfig，如图：

　　代码如下，可自行copy更改：

package com.xykj.blog.config;

import com.mangofactory.swagger.configuration.SpringSwaggerConfig;
import com.mangofactory.swagger.models.dto.ApiInfo;
import com.mangofactory.swagger.plugin.EnableSwagger;
import com.mangofactory.swagger.plugin.SwaggerSpringMvcPlugin;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;

@Configuration
@EnableSwagger
@EnableWebMvc
public class SwaggerConfig {

    private SpringSwaggerConfig springSwaggerConfig;

    /**
     * Required to autowire SpringSwaggerConfig
     */
    @Autowired
    public void setSpringSwaggerConfig(SpringSwaggerConfig springSwaggerConfig)
    {
        this.springSwaggerConfig = springSwaggerConfig;
    }

    /**
     * Every SwaggerSpringMvcPlugin bean is picked up by the swagger-mvc
     * framework - allowing for multiple swagger groups i.e. same code base
     * multiple swagger resource listings.
     */
    @Bean
    public SwaggerSpringMvcPlugin customImplementation()
    {
        return new SwaggerSpringMvcPlugin(this.springSwaggerConfig)
                .apiInfo(apiInfo())
                .includePatterns(".*");
    }

    private ApiInfo apiInfo()
    {
        ApiInfo apiInfo = new ApiInfo(
                "Swagger测试",
                "测试查询用户",
                "开发者: Changxin L",
                "348686686@gmail.com",
                "MIT License",
                "/LICENSE");
        return apiInfo;
    }
}

　　接下来，在spring mvc的配置文件内，注入该配置类

类路径，按你自己的实际情况进行更改。

　　然后在需要使用swagger生成api文档的controller文件上测试使用，如下：

运行项目，在项目url + /api-docs访问Swagger返回的api信息(json格式):

　　到这里，spring mvc已经集成并可以使用swagger来生成、描述api了。

　　下面，我们来使用swagger ui来解析这段json，可视化api文档：

　　准备工作：在webapp下新建一个文件夹，名称自定义，我这里命名为swagger

　　首先，到这里下载swagger ui，压缩后，找到dist文件，将dist目录下的所有文件，复制到webapp/swagger下，然后在spring mvc的配置文件中添加静态文件映射：

　　最后，在刚刚拷贝到swagger 的文件内找到index.xml，更改如下：

　　图中画线地方，改为你自己项目的地址+/api-docs(其实就是在上面测试到可以获取swagger返回json的那个url)。

　　运行项目，使用：项目url + /swagger/index.xml来访问swagger ui。(Ps:这里的/swagger/，就是spring mvc配置文件的映射url，如下图：)

　　如果上述操作准确无误的话，那么你将会看到如下界面：