900字范文 > Spring MVC集成Swagger2.0

Spring MVC集成Swagger2.0

时间：2020-09-03 20:42:54

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

OpenAPI

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

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

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

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

Swagger Editor：API设计器，基于浏览器的在线编辑器；

Swagger UI：根据API的描述信息生成文档，可以查看和测试API；Swagger Codegen：根据API的设计文档，生成需要的服务端或客户端代码；

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

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

一、定义API接口文档

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

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

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

wget /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的引用即可：

<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类。