SpringBoot入门——使用Swagger2构建Restful API文档

自己写程序测试时写的，不喜勿喷，可能有错，欢迎纠正

一、背景

由于Spring Boot能够快速开发、便捷部署等特性，相信有很大一部分Spring Boot的用户会用来构建RESTful API。而我们构建RESTful API的目的通常都是由于多终端的原因，这些终端会共用很多底层业务逻辑，因此我们会抽象出这样一层来同时服务于多个移动端或者Web前端。

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

• 由于接口众多，并且细节复杂（需要考虑不同的HTTP请求类型、HTTP头部信息、HTTP请求内容等），高质量地创建这份文档本身就是件非常吃力的事，下游的抱怨声不绝于耳。
• 随着时间推移，不断修改接口实现的时候都必须同步修改接口文档，而文档与代码又处于两个不同的媒介，除非有严格的管理机制，不然很容易导致不一致现象。

为了解决上面这样的问题，本文将介绍RESTful API的重磅好伙伴Swagger2，它可以轻松的整合到Spring Boot中，并与Spring MVC程序配合组织出强大RESTful API文档。它既可以减少我们创建文档的工作量，同时说明内容又整合入实现代码中，让维护文档和修改代码整合为一体，可以让我们在修改代码逻辑的同时方便的修改文档说明。另外Swagger2也提供了强大的页面测试功能来调试每个RESTful API。

二、Swagger简介

Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。本文简单介绍了在项目中集成swagger的方法和一些常见问题。

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

三、SpringBoot中应用Swagger2

(1)、新建Maven项目

项目名称:springboot

(2)、在pom中引入Springboot项目需要的包

新建Maven项目，往其中pom.xml中引入Springboot需要的包

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"><modelVersion>4.0.0</modelVersion><groupId>com.springboot</groupId><artifactId>spring-boot2</artifactId><version>0.0.1-SNAPSHOT</version><packaging>jar</packaging><name>springboot</name><url>http://maven.apache.org</url><parent><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-parent</artifactId><version>1.5.4.RELEASE</version></parent><properties><project.build.sourceEncoding>UTF-8</project.build.sourceEncoding><java.version>1.8</java.version></properties><dependencies><!-- web --><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency><!-- Springboot devtools热部署 依赖包 --><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-devtools</artifactId><optional>true</optional><scope>true</scope></dependency></dependencies><build><plugins><plugin><groupId>org.springframework.boot</groupId><artifactId>spring-boot-maven-plugin </artifactId><configuration><!-- 如果没有该项配置，devtools不会起作用，即应用不会restart --><fork>true</fork></configuration></plugin></plugins></build></project>

(3)、在pom中引入Swagger需要的包

         <dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.7.0</version></dependency><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>2.7.0</version></dependency>

(4)、创建Swagger2配置类

包名：com.springboot.config

类名：SwaggerConfig

package com.springboot.config;import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;@Configuration
// 启用swagger
@EnableSwagger2
public class SwaggerConfig {@Beanpublic Docket createRestApi() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(this.apiInfo()).groupName("XX组").useDefaultResponseMessages(false).enableUrlTemplating(false).select().apis(RequestHandlerSelectors.basePackage("com.springboot.controller")).paths(PathSelectors.any()).build();}private ApiInfo apiInfo() {return new ApiInfoBuilder().title("Spring Boot Swagger2 By Test").description("XX项目API").termsOfServiceUrl("127.0.0.1:8080/test/").version("0.0.1").build();}
}

参数说明：

----------------------------------------------------------------------------------

• @Configuration：声明此类为配置类,让Spring加载
• @EnableSwagger2：启用Swagger2

----------------------------------------------------------------------------------

• apiInfo()：创建该Api的基本信息
• groupName()：设置组名
• useDefaultResponseMessages()：使用默认的响应信息，一般设置false
• enableUrlTemplating(false)：使模板的URL

----------------------------------------------------------------------------------

• apis()：扫描哪些包
• PathSelectors.any()：任何满足条件的路径

----------------------------------------------------------------------------------

(5)、创建Controller类

包名：com.springboot.controller;

类名：HelloController

package com.springboot.controller;import static org.springframework.util.MimeTypeUtils.APPLICATION_JSON_VALUE;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;
import com.springboot.entity.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;@RestController
@RequestMapping("/test")
@Api(tags="与检查单有关的接口")
public class HelloController {@ApiOperation(value = "获得hello字符串JSON", response = String.class, produces = APPLICATION_JSON_VALUE,notes = "根据User对象创建用户")@RequestMapping(value = { "/hello" }, method = RequestMethod.GET)public String hello() {return "hello";}@ApiOperation(value = "修改用户", response = String.class, produces = APPLICATION_JSON_VALUE,notes = "根据id修改用户")@ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")@RequestMapping(value = { "/modifyUser" }, method = RequestMethod.POST) public User modifyUser(@RequestBody User user) {user.setName("张三");user.setAge(20);return user;}}

参数说明：

----------------------------------------------------------------------------------

• @Api：对Controller项的标题描述信息设置
• @ApiOperation：对接口信息进行描述

1. name：参数名
2. value：参数描述信息
3. required：是否可以发送请求信息进行测试
4. dataType：数据类型

• @ApiImplicitParam：对接口的方法的参数进行描述

1. value：操作项名字设置
2. response：返回类型设置
3. response：返回数据格式
4. notes：此项的描述信息

----------------------------------------------------------------------------------

三、管理接口的地址

http://localhost:8080/swagger-ui.html