Spring MVC集成Swagger2.0

　　在集成Swagger之前，得先说说什么是Swagger，它是用来做什么的，然后再讲讲怎么集成，怎么使用，当然，在这之前，需要了解一下OpenAPI。

• OpenAPI

　　OpenAPI 3.0规范定义了一个标准的、语言无关的RESTful APIs，它可以被人和机器所理解和使用，而不需要查找其源码、说明文档或其他方面。如果属性定义正确的话，消费者可以使用少量的逻辑代码与远程服务进行交互。可以使用OpenAPI的接口定义文件生成相应的文档、服务端接口、客户端接口和其他单元测试等等。

　　简单的来说，就是通过这套规范，先定义接口，再根据定义文件生成相应语言的接口代码，之后可以来进行具体逻辑编写。一次定义，可多次使用。其定义的接口文档主要包含以下内容：

1. 可访问的端点（endpoints ）和每个端点的操作（(GET /users, POST /users）；
2. 每个端点的输入输出参数；
3. 授权方式；
4. 联系方式、团队名称、作者等其他信息；

• Swagger

　　swagger是一个可以帮助你设计、构建代码、生成文档和测试API的工具集合，它是根据OpenAPI的规范具体实现的开源工具。包含以下几个工具：

1. Swagger Editor：API设计器，基于浏览器的在线编辑器；
   
2. Swagger UI ：根据API的描述信息生成文档，可以查看和测试API；
3. Swagger Codegen ：根据API的设计文档，生成需要的服务端或客户端代码；

　　使用它的意义主要在于，接口的规范化开发，文档的快速生成。开发最头疼的就是写文档，这样的话，可以省去大把的时间，而且，这样也利于团队的开发和新人的快速加入，也在系统集成时更加的方便。

---

　　废话不多说，开始在Spring MVC中集成Swagger框架。

一、定义API接口文档

　　我们不具体说明编写过程，使用Swagger提供的样例“宠物商店”（http://petstore.swagger.io/v2/swagger.json）。

二、使用代码生成工具生成Java代码

　　代码构建工具Codegen（删改你介绍时有Github地址），我们先需要下载构建工具包：

wget http://central.maven.org/maven2/io/swagger/swagger-codegen-cli/2.4.0/swagger-codegen-cli-2.4.0.jar -O swagger-codegen-cli.jar

　　具体使用方法，可参见其Github项目中的描述。生成代码命令：

java -jar swagger-codegen-cli-2.4.0.jar generate -i http://petstore.swagger.io/v2/swagger.json -l spring --library spring-mvc -o tmp

　　参数-l时指语言类型，--library指的是使用的库，spring-mvc、spring-boot或者spring-cloud，默认生成spring-boot的代码。其中的目录截图：

　　 

　　其中的配置目录，

　　

三、引入Swagger的依赖包

　复制生成项目中pom的引用即可：

        <!--SpringFox dependencies -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${springfox-version}</version>
            <exclusions>
                <exclusion>
                    <groupId>com.fasterxml.jackson.core</groupId>
                    <artifactId>jackson-annotations</artifactId>
                </exclusion>
            </exclusions>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${springfox-version}</version>
        </dependency>

 四、合入代码

　　将api和model下面的放入对应包结构下，但是configuration中的需要重新配置。因为项目已经配置了MVC，如果直接使用，则会初始化两次mvc的信息，故不使用WebMvcConfiguration和WebApplication两个类。SwaggerUiConfiguration类为配置的入口，里面含有Swagger的配置注解，需要再初始化MVC的时候，加载这个类。SwaggerDocumentationConfig类为Swagger文档的配置类，其中有api的包路径设置，设置正确才能解析出。为了防止启动时候，初始化spring的时候加载这些配置，这些类不能放到基础扫描包里面。再spring-mvc中添加配置想，单独加载SwaggerUiConfiguration类。

五、启动并访问

　　如看到这些信息，则说明启动成功，可以访问：

 　　访问地址：http://localhost:8080/webapp/swagger-ui.html，效果如下：

六、增加配置项，上线后禁用Swagger-UI功能

　　spring-mvc.xml中配置如下：

<import resource="classpath*:springfox-${springfox.swagger.mode:default}-swagger.xml"/>

　　设置VM的启动变量，-Dspringfox.swagger.mode=dev，新增springfox-dev-swagger.xml配置文件，里面加载SwaggerUiConfiguration类。

本文中的代码和配置均已提交Github：https://github.com/FlowerBirds/JavaDemoApp，可以参考。

参考文档：

• https://swagger.io/docs/specification/about/
• https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md

本文作者：风雨咒之无上密籍