Swagger 简介
Swagger 是一套基于 OpenAPI 规范构建的开源工具，可以帮助我们设计、构建、记录以及使用 Rest API。Swagger 主要包含了以下三个部分：
- Swagger Editor：基于浏览器的编辑器，我们可以使用它编写我们 OpenAPI 规范。
- Swagger UI：它会将我们编写的 OpenAPI 规范呈现为交互式的 API 文档，后文我将使用浏览器来查看并且操作我们的 Rest API。
- Swagger Codegen：它可以通过为 OpenAPI（以前称为 Swagger）规范定义的任何 API 生成服务器存根和客户端 SDK 来简化构建过程。
为什么要使用 Swagger
当下很多公司都采取前后端分离的开发模式，前端和后端的工作由不同的工程师完成。在这种开发模式下，维持一份及时更新且完整的 Rest API 文档将会极大的提高我们的工作效率。传统意义上的文档都是后端开发人员手动编写的，相信大家也都知道这种方式很难保证文档的及时性，这种文档久而久之也就会失去其参考意义，反而还会加大我们的沟通成本。而 Swagger 给我们提供了一个全新的维护 API 文档的方式，下面我们就来了解一下它的优点：
- 代码变，文档变。只需要少量的注解，Swagger 就可以根据代码自动生成 API 文档，很好的保证了文档的时效性。
- 跨语言性，支持 40 多种语言。
- Swagger UI 呈现出来的是一份可交互式的 API 文档，我们可以直接在文档页面尝试 API 的调用，省去了准备复杂的调用参数的过程。
- 还可以将文档规范导入相关的工具（例如 SoapUI）, 这些工具将会为我们自动地创建自动化测试。
Swagger 使用
准备项目
1、准备一个Spring的Maven Web项目（test-swagger），参考：，pom.xml文件如下：
1 <project xmlns="http://maven.apache.org/POM/4.0.0" 2 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 3 xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd"> 4 <modelVersion>4.0.0</modelVersion> 5 <groupId>com.test</groupId> 6 <artifactId>test-swagger</artifactId> 7 <packaging>war</packaging> 8 <version>1.0-SNAPSHOT</version> 9 10 <!-- 定义maven变量 --> 11 <properties> 12 <!-- spring --> 13 <spring.version>5.1.4.RELEASE</spring.version> 14 15 <!-- log --> 16 <commons-logging.version>1.1.3</commons-logging.version> 17 18 <!-- Servlet --> 19 <servlet.version>3.0.1</servlet.version> 20 <jsp-api.version>2.2</jsp-api.version> 21 22 <!-- jstl --> 23 <jstl.version>1.2</jstl.version> 24 <standard.version>1.1.2</standard.version> 25 26 <!-- Tool --> 27 <!-- jackson json包 --> 28 <jackson-databind.version>2.9.7</jackson-databind.version> 29 <jackson-core.version>2.9.7</jackson-core.version> 30 <jackson-annotations.version>2.9.7</jackson-annotations.version> 31 32 <!-- test --> 33 <junit.version>3.8.1</junit.version> 34 35 <!-- jdk --> 36 <jdk.version>1.8</jdk.version> 37 <maven.compiler.plugin.version>2.3.2</maven.compiler.plugin.version> 38 </properties> 39 40 41 <dependencies> 42 43 <dependency> 44 <groupId>org.springframework</groupId> 45 <artifactId>spring-core</artifactId> 46 <version>${spring.version}</version> 47 </dependency> 48 49 <dependency> 50 <groupId>org.springframework</groupId> 51 <artifactId>spring-beans</artifactId> 52 <version>${spring.version}</version> 53 </dependency> 54 55 <dependency> 56 <groupId>org.springframework</groupId> 57 <artifactId>spring-context</artifactId> 58 <version>${spring.version}</version> 59 </dependency> 60 61 <dependency> 62 <groupId>org.springframework</groupId> 63 <artifactId>spring-jdbc</artifactId> 64 <version>${spring.version}</version> 65 </dependency> 66 67 68 <dependency> 69 <groupId>org.springframework</groupId> 70 <artifactId>spring-expression</artifactId> 71 <version>${spring.version}</version> 72 </dependency> 73 74 <dependency> 75 <groupId>org.springframework</groupId> 76 <artifactId>spring-web</artifactId> 77 <version>${spring.version}</version> 78 </dependency> 79 80 <dependency> 81 <groupId>org.springframework</groupId> 82 <artifactId>spring-webmvc</artifactId> 83 <version>${spring.version}</version> 84 </dependency> 85 86 <dependency> 87 <groupId>org.springframework</groupId> 88 <artifactId>spring-tx</artifactId> 89 <version>${spring.version}</version> 90 </dependency> 91 92 93 94 95 <!-- Servlet --> 96 <dependency> 97 <groupId>javax.servlet</groupId> 98 <artifactId>javax.servlet-api</artifactId> 99 <version>${servlet.version}</version> 100 <scope>provided</scope> 101 </dependency> 102 <dependency> 103 <groupId>javax.servlet.jsp</groupId> 104 <artifactId>jsp-api</artifactId> 105 <version>${jsp-api.version}</version> 106 <scope>provided</scope> 107 </dependency> 108 109 <!-- jstl --> 110 <dependency> 111 <groupId>javax.servlet</groupId> 112 <artifactId>jstl</artifactId> 113 <version>${jstl.version}</version> 114 </dependency> 115 116 <dependency> 117 <groupId>taglibs</groupId> 118 <artifactId>standard</artifactId> 119 <version>${standard.version}</version> 120 </dependency> 121 122 123 <!-- jackson json包 --> 124 <dependency> 125 <groupId>com.fasterxml.jackson.core</groupId> 126 <artifactId>jackson-databind</artifactId> 127 <version>${jackson-databind.version}</version> 128 </dependency> 129 130 <dependency> 131 <groupId>com.fasterxml.jackson.core</groupId> 132 <artifactId>jackson-core</artifactId> 133 <version>${jackson-core.version}</version> 134 </dependency> 135 136 <dependency> 137 <groupId>com.fasterxml.jackson.core</groupId> 138 <artifactId>jackson-annotations</artifactId> 139 <version>${jackson-annotations.version}</version> 140 </dependency> 141 142 <!-- swagger --> 143 <dependency> 144 <groupId>io.springfox</groupId> 145 <artifactId>springfox-swagger2</artifactId> 146 <version>2.9.2</version> 147 </dependency> 148 149 <dependency> 150 <groupId>io.springfox</groupId> 151 <artifactId>springfox-swagger-ui</artifactId> 152 <version>2.9.2</version> 153 </dependency> 154 155 <!-- test --> 156 <dependency> 157 <groupId>junit</groupId> 158 <artifactId>junit</artifactId> 159 <version>${junit.version}</version> 160 <scope>test</scope> 161 </dependency> 162 163 </dependencies> 164 165 166 <build> 167 <plugins> 168 <!-- define the project compile level --> 169 <plugin> 170 <groupId>org.apache.maven.plugins</groupId> 171 <artifactId>maven-compiler-plugin</artifactId> 172 <version>${maven.compiler.plugin.version}</version> 173 <configuration> 174 <source>${jdk.version}</source> 175 <target>${jdk.version}</target> 176 </configuration> 177 </plugin> 178 </plugins> 179 <finalName>test-swagger</finalName> 180 </build> 181 182 </project>