SpringBoot整合Swagger2详细教程

1. 简介

  随着前后端分离开发模式越来越流行，编写接口文档变成了开发人员非常头疼的事。而Swagger是一个规范且完整的web框架，用于生成、描述、调用可视化的RESTful风格的在线接口文档，并解决手写文档时编写和更新以及测试的复杂问题。

2. 示例代码

• 创建项目
  
• 修改pom.xml

<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 https://maven.apache.org/xsd/maven-4.0.0.xsd">
	<modelVersion>4.0.0</modelVersion>
	<groupId>com.c3stones</groupId>
	<artifactId>spring-boot-swagger2-demo</artifactId>
	<version>0.0.1-SNAPSHOT</version>
	<name>spring-boot-swagger2-demo</name>
	<description>Spring Boot Swagger2 Demo</description>

	<parent>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-parent</artifactId>
		<version>2.2.8.RELEASE</version>
		<relativePath />
	</parent>

	<dependencies>
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger2</artifactId>
			<version>2.9.2</version>
		</dependency>
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger-ui</artifactId>
			<version>2.9.2</version>
		</dependency>
		<dependency>
			<groupId>org.projectlombok</groupId>
			<artifactId>lombok</artifactId>
		</dependency>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-web</artifactId>
		</dependency>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-test</artifactId>
			<scope>test</scope>
		</dependency>
	</dependencies>

</project>

• 创建Swagger2配置类

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;

/**
 * Swagger2配置类
 * 
 * @author CL
 *
 */
@Configuration
@EnableSwagger2
public class Swagger2Config {

	/**
	 * 注入Docket
	 * 
	 * @return
	 */
	@Bean
	public Docket docket() {
		return new Docket(DocumentationType.SWAGGER_2).apiInfo(setApiInfo()).select()
				.apis(RequestHandlerSelectors.basePackage("com.c3stones.controller")).paths(PathSelectors.any())
				.build();
	}

	/**
	 * 配置在线文档的基本信息
	 * 
	 * @return
	 */
	private ApiInfo setApiInfo() {
		return new ApiInfoBuilder().title("SpringBoot整合Swagger2示例")
				.description("<a href='https://www.cnblogs.com/cao-lei/' target='_blank'>欢迎访问我的博客</a>")
				.termsOfServiceUrl("https://www.cnblogs.com/cao-lei/").version("V1.0").build();
	}

}

• 创建实体

import lombok.AllArgsConstructor;
import lombok.Data;

/**
 * 用户信息
 * 
 * @author CL
 *
 */
@Data
@AllArgsConstructor
public class User {

	/**
	 * 用户ID
	 */
	private Long id;

	/**
	 * 用户名称
	 */
	private String username;

	/**
	 * 年龄
	 */
	private Integer age;

}

• 创建Controller

import java.util.ArrayList;
import java.util.List;

import org.springframework.http.HttpRequest;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.ResponseBody;
import org.springframework.web.bind.annotation.RestController;

import com.c3stones.entity.User;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import springfox.documentation.annotations.ApiIgnore;

/**
 * 用户Controller
 * 
 * @author CL
 *
 */
@Api(tags = "User / 用户信息")
@RestController
@RequestMapping(value = "/user")
public class UserController {

	/**
	 * 获取用户信息
	 * 
	 * @param user 用户信息
	 * @return
	 */
	@RequestMapping(value = "/get", method = RequestMethod.GET)
	@ResponseBody
	@ApiOperation(value = "获取用户信息")
	@ApiImplicitParams({ @ApiImplicitParam(name = "id", value = "用户ID", required = true, type = "Long"),
			@ApiImplicitParam(name = "username", value = "用户名称", type = "String"),
			@ApiImplicitParam(name = "age", value = "年龄", type = "Integer") })
	public User get(User user) {
		return new User(1L, "C3Stones", 23);
	}

	/**
	 * 获取用户列表
	 * 
	 * @param user 用户信息
	 * @return
	 */
	@SuppressWarnings("serial")
	@RequestMapping(value = "/listData", method = { RequestMethod.GET, RequestMethod.POST })
	@ResponseBody
	@ApiOperation(value = "获取用户列表")
	@ApiImplicitParams({ @ApiImplicitParam(name = "id", value = "用户ID", type = "Long"),
			@ApiImplicitParam(name = "username", value = "用户名称", type = "String"),
			@ApiImplicitParam(name = "age", value = "年龄", type = "Integer") })
	public List<User> listData(User user, @ApiIgnore HttpRequest request) {
		return new ArrayList<User>() {
			{
				add(new User(1L, "张三", 23));
				add(new User(2L, "李四", 24));
				add(new User(3L, "王五", 25));
			}
		};
	}
}

• 创建启动类

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

/**
 * 启动类
 * 
 * @author CL
 *
 */
@SpringBootApplication
public class Application {

	public static void main(String[] args) {
		SpringApplication.run(Application.class, args);
	}

}

3. 测试

• 启动项目
• 浏览器访问

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

4. 项目地址

  spring-boot-swagger2-demo