SpringBoot使用Swagger2

现在好多公司招聘开发人员都是前后端分离的，所以大家分工很明确，Spring为我们解决了书写API文档的麻烦，那么我们接下来就一起来看下如何使用Swagger2吧，希望大家会喜欢。

1. 搭建基础的SpringBoot项目
   项目结构，如下：
   
   POM依赖，如下：

<?xml version="1.0" encoding="UTF-8"?>
<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>
	<parent>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-parent</artifactId>
		<version>2.2.0.RELEASE</version>
		<relativePath/> <!-- lookup parent from repository -->
	</parent>
	<groupId>com.example</groupId>
	<artifactId>demo</artifactId>
	<version>0.0.1-SNAPSHOT</version>
	<name>demo</name>
	<description>Demo project for Spring Boot</description>

	<properties>
		<java.version>1.8</java.version>
	</properties>

	<dependencies>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-web</artifactId>
		</dependency>
		
		<!-- Swagger2依赖 -->
		<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.springframework.boot</groupId>
			<artifactId>spring-boot-starter-test</artifactId>
			<scope>test</scope>
			<exclusions>
				<exclusion>
					<groupId>org.junit.vintage</groupId>
					<artifactId>junit-vintage-engine</artifactId>
				</exclusion>
			</exclusions>
		</dependency>
	</dependencies>

	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
			</plugin>
		</plugins>
	</build>

</project>

待到Jar全部下载完毕后，我们就开始书写代码。
2. 添加Swagger2配置
我在conf包中添加了一个配置类，它是用来配置Swagger2的，当我们打开Swagger2的界面时，会展示我们配置的部分信息。

package com.example.demo.conf;

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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

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

	@Bean
	public Docket createRestApi() {
		return new Docket(DocumentationType.SWAGGER_2)
				.apiInfo(apiInfo())
				.select()
				.apis(RequestHandlerSelectors.basePackage("com.example.demo"))  //这个地方是扫描的包
				.paths(PathSelectors.any())
				.build();
	}
	
	private ApiInfo apiInfo() {
		return new ApiInfoBuilder()
				.title("springboot利用swagger构建api文档")												// 标题
				.description("简单优雅的restfun风格")														// 描述
				.termsOfServiceUrl("http://localhost:8090/")										// 你可以写你的项目访问地址，或者可以不写。
				.contact(new Contact("PGQing","https://blog.csdn.net/P923284735","[e-mail]"))	// 关于作者的地方，比如你的名字，博客地址，你的邮箱地址
				.version("1.0")																		// 版本
				.build();
	}
}

3. 编写代码
   控制层

package com.example.demo.controller;

import java.util.HashMap;
import java.util.Map;

import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;

@RestController
@RequestMapping("/user")
@Api(tags = "用户业务请求控制器")
public class UserController {

	@ApiOperation("保存用户信息")
	@RequestMapping("/saveUserInfo")
	@ApiImplicitParams({ @ApiImplicitParam(name = "name", value = "用户名"), @ApiImplicitParam(name = "age", value = "年龄"),
			@ApiImplicitParam(name = "phone", value = "手机号"), })
	public String saveUserInfo(@RequestParam(required = true) String name, @RequestParam(required = true) int age,
			@RequestParam(required = true) String phone) {
		Map<String, Object> map = new HashMap<String, Object>();
		map.put("name", name);
		map.put("age", age);
		map.put("phone", phone);
		return map.toString();
	}
}

@ApiOperation 对于该方法的业务描述
@ApiImplicitParams 包含的多个参数，类似数组
@ApiImplicitParam 参数，属性包含：name、value等

实体类

package com.example.demo.entity;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel(description = "用户实体类")
public class User {
	
	@ApiModelProperty(value = "用户名")
	private String name;
	@ApiModelProperty(value = "年龄")
	private int age;
	@ApiModelProperty(value = "手机号")
	private String phone;

	public String getName() {
		return name;
	}

	public void setName(String name) {
		this.name = name;
	}

	public int getAge() {
		return age;
	}

	public void setAge(int age) {
		this.age = age;
	}

	public String getPhone() {
		return phone;
	}

	public void setPhone(String phone) {
		this.phone = phone;
	}

}

@ApiModelProperty 加在实体类的属性
@ApiModel 需要加在实体类

application.properties配置

server.port=8090
server.servlet.context-path=/demo
spring.application.name=swagger2Demo

5. 访问Swagger2提供API文档
   接下来我们根据application.properties中配置的，访问API文档，
   
6. 测试接口是否可用
   接下来我们访问一下刚才我们写好的接口，看看是否可用。
   
   
   
   这就是Swagger2的简单使用了。