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

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 {
@Bean
public 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：对接口信息进行描述

name：参数名

value：参数描述信息

required：是否可以发送请求信息进行测试

dataType：数据类型

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

value：操作项名字设置

response：返回类型设置

response：返回数据格式

notes：此项的描述信息

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

三、管理接口的地址

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