记一次 SpringBoot 2.x 整合 Swagger2

QQ交流群：64655993 希望能对您有所帮助！！！

环境说明：

Eclipse版本： eclipse-jee-photon-R-win32-x86_64

JDK：1.8

Maven：3.6.0

特点：

• 功能丰富：支持多种注解，自动生成接口文档界面，支持在界面测试API接口功能；
• 及时更新：开发过程中花一点写注释的时间，就可以及时的更新API文档，省心省力；
• 整合简单：通过添加pom依赖和简单配置，内嵌于应用中就可同时发布API接口文档界面，不需要部署独立服务。

第一部分：项目创建

1、创建一个maven项目，右键新建项目，选择Other

2、选择 Maven Project

3、点击下一步  选择工作空间

4、选择项目类型  webapp

5、录入项目名等基本信息

6、刚创建好的样子（文件结构）

注意：此时可能会报错，解决方案如下

javascript:void(0)

7、对创建好的项目，设置对应的JDK版本

8、项目正常的样子（可以开发）

9、项目目录结构

第二部分：源代码

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 http://maven.apache.org/maven-v4_0_0.xsd">
	<modelVersion>4.0.0</modelVersion>
	<groupId>SpringBootSwagger</groupId>
	<artifactId>SpringBootSwagger</artifactId>
	<packaging>war</packaging>
	<version>0.0.1-SNAPSHOT</version>
	<name>SpringBootSwagger Maven Webapp</name>
	<url>http://maven.apache.org</url>
	<parent>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-parent</artifactId>
		<version>2.0.3.RELEASE</version>
		<relativePath />
	</parent>
	<dependencies>
		<dependency>
			<groupId>junit</groupId>
			<artifactId>junit</artifactId>
			<scope>test</scope>
		</dependency>
		<!--spring-boot -->
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter</artifactId>
		</dependency>
		<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.6.1</version>
		</dependency>
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger-ui</artifactId>
			<version>2.6.1</version>
		</dependency>
	</dependencies>
	<build>
		<finalName>SpringBootSwagger</finalName>
	</build>
</project>

Swagger2.java

package com.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
@EnableSwagger2
public class Swagger2 {
	//swagger2的配置文件，这里可以配置swagger2的一些基本的内容，比如扫描的包等等
    @Bean  
    public Docket createRestApi() {// 创建API基本信息  
        return new Docket(DocumentationType.SWAGGER_2)  
                .apiInfo(apiInfo())  
                .select()  
                .apis(RequestHandlerSelectors.basePackage("com.controller"))// 扫描该包下的所有需要在Swagger中展示的API，@ApiIgnore注解标注的除外  
                .paths(PathSelectors.any())  
                .build();  
    }  
    private ApiInfo apiInfo() {// 创建API的基本信息，这些信息会在Swagger UI中进行显示  
        return new ApiInfoBuilder()  
                .title("Swagger接口文档")
                .description("Swagger-接口文档")// API描述  
                .version("1.0.0")// 版本号  
                .build();  
    }  
}

UserInput.java

package com.input;
public class UserInput {
	private String userName;
	private String passWord;
	public String getUserName() {
		return userName;
	}
	public void setUserName(String userName) {
		this.userName = userName;
	}
	public String getPassWord() {
		return passWord;
	}
	public void setPassWord(String passWord) {
		this.passWord = passWord;
	}
}

SwaggerController.java

package com.controller;
import org.springframework.stereotype.Controller;
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.RequestParam;
import org.springframework.web.bind.annotation.ResponseBody;
import com.input.UserInput;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
@Api(value = "Swagger 接口平台 api")
@Controller
public class SwaggerController {
	/**
	 * Post请求 保存用户信息
	 * @param input
	 * @return String
	 */
	@ApiOperation(value = "Post请求 保存用户信息")
	@ResponseBody
	@RequestMapping(method = RequestMethod.POST, value = "/user/postUser")
	public String postUser(@RequestBody UserInput input) {
		return "保存用户："+input.getUserName()+"   操作成功！";
	}
	/**
	 * Get 请求 获取用户信息
	 * @param id
	 * @return String
	 */
	//或者 @GetMapping(value = "/user/getUser")
	@ApiOperation(value = "Get 请求 获取用户信息")
	@ResponseBody
	@RequestMapping(method = RequestMethod.GET, value = "/user/getUser")
	public String getUser(@RequestParam Integer id) {
		String userName = "Swagger";
		return "您获取的用户名是："+userName;
	}
}

Application.java

package com;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.EnableAutoConfiguration;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.web.servlet.ServletComponentScan;
import org.springframework.cache.annotation.EnableCaching;
@EnableAutoConfiguration()
@ServletComponentScan
@SpringBootApplication
@EnableCaching
public class Application {
	public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
        System.out.println("   ==================================");
        System.out.println("        Swagger接口系统启动成功！");
        System.out.println("   ==================================");
    }
}

第三部分：运行、效果

1、右键运行主程序：

 Application.java   =》  Run As   =》 Java Application

说明：此处没有配置  application.yml ，所以默认端口是 8080 ，如有其它端口要求，可自行配置 application.yml 文件。

2、控制台运行成功的效果：

3、浏览器查看

打开浏览器，输入地址：   http://localhost:8080/swagger-ui.html

4、实际操作（GET 请求）

5、实际操作（POST 请求）

 

至此，SpringBoot 整合 Swagger2 完毕 ！

 

Swagger2通过注解来生成API接口文档，文档信息包括 接口名、请求方法、参数、返回信息等。通常情况下用于生成在线API文档：
        @Api：修饰整个类，用于描述Controller类
        @ApiOperation：描述类的方法，或者说一个接口
        @ApiParam：单个参数描述
        @ApiProperty：用对象接收参数时，描述对象的一个字段。
        @ApiResponse：HTTP响应的一个描述
        @ApiResponses：HTTP响应的整体描述
        @ApiIgnore：使用该注解，表示Swagger2忽略这个API
        @ApiError：发生错误返回的信息
        @ApiParamImplicit：一个请求参数
        @ApiParamsImplicit：多个请求参数

参数说明
1. name ：参数名。
2. value ： 参数的具体意义，作用。
3. required ： 参数是否必填。
4. dataType ：参数的数据类型。
5. paramType ：查询参数类型，这里有几种形式：
@ApiImplicitParams：
用于方法，包含多个 @ApiImplicitParam。
@Api：
作用在类上，用来标注该类具体实现内容。标识这个类是swagger的资源 。
参数：
1. tags：允许您为操作设置多个标签的属性。
2. description：可描述该类的作用。