投稿
  1. 极客之音首页
  2. 技术随笔

SpringBoot与Swagger2.0集成

小半 • • 技术随笔 • 阅读 318

导读：本篇文章讲解 SpringBoot与Swagger2.0集成，希望对大家有帮助，欢迎收藏，转发！站点地址：www.bmabk.com

SpringBoot与Swagger2.0集成

前言

案例github地址（如果有用点个star呗） https://github.com/chenxiban/BlogCaseSet.git

Swagger简介

随着互联网技术的发展，现在的网站架构基本都由原来的后端渲染，变成了：前端渲染、先后端分离的形
态，而且前端技术和后端技术在各自的道路上越走越远。 前端和后端的唯一联系，变成了API接口；API文档
变成了前后端开发人员联系的纽带，变得越来越重要， swagger 就是一款让你更好的书写API文档的框架。
Swagger是全球最大的开源API开发工具框架，支持从设计和文档到测试和部署的整个API生命周期的开发。
在实际开发中，有的项目是为客户端（安卓端、IOS端、微信公众号、小程序等）提供服务的，这样的形式叫
做“前后端分离”，我们作为服务端提供接口文档供客户端调用。测试时使用postman，接口地址拼写容易出
错，文档的更新与维护工作比较繁琐。由此可见，手写Api文档的几个痛点：

  • swagger的出现就是为了方便进行测试后台的restful形式的接口，实现动态的更新，当我们在后台的接口修
    改了后，swagger可以实现自动的更新，而不需要人为的维护这个接口进行测试。
  • 文档需要更新的时候，需要再次发送一份给前端，也就是文档更新交流不及时。 接口返回结果不明确。 不能直接在线测试接口，通常需要使用工具，比如postman。 接口文档太多，不好管理。

swagger的出现就是为了方便进行测试后台的restful形式的接口，实现动态的更新，当我们在后台的接口修
改了后，swagger可以实现自动的更新，而不需要人为的维护这个接口进行测试。

Springboot集成Swagger2的步骤

项目结构如下

在这里插入图片描述

添加依赖

首先需要在pom.xml 文件中添加Swagger2的依赖：

<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.cyj</groupId>
	<artifactId>springboot-swagger2</artifactId>
	<version>0.0.1-SNAPSHOT</version>
	<packaging>jar</packaging>


	<name>springboot-swagger2</name>

	<!-- 项目设置:编码格式UTF-8 -->
	<properties>
		<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
		<project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
		<java.version>1.8</java.version>
	</properties>
	<!-- Spring Boot 启动父依赖 -->
	<parent>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-parent</artifactId>
		<version>2.0.4.RELEASE</version>
	</parent>

	<dependencies>
		<!-- Spring Boot SpringMVC框架依赖 -->
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-web</artifactId>
		</dependency>
		<!-- Spring Boot swagger2框架依赖 -->
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger2</artifactId>
			<version>2.6.1</version>
		</dependency>
		<!-- Spring Boot swagger-ui框架依赖 -->
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger-ui</artifactId>
			<version>2.6.1</version>
		</dependency>
		<!-- lombok 依赖 -->
        <dependency>
			<groupId>org.projectlombok</groupId>
			<artifactId>lombok</artifactId>
		</dependency>
		<!-- 热部署 -->
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-devtools</artifactId>
			<optional>true</optional><!-- optional=true,依赖不会传递，该项目依赖devtools；之后依赖myboot项目的项目如果想要使用devtools，需要重新引入 -->
			<scope>true</scope><!-- 热部署 -->
		</dependency>
	</dependencies>
	<build>
		<plugins>
			<!-- SpringBoot项目打jar包的Maven插件 -->
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
			</plugin>
		</plugins>
		<!-- SpringBoot项目打包jar名称 -->
		<finalName>swagger2</finalName>

	</build>
</project>

控制器类中使用swagger注解

  1. 常用注解
    1. @Api：修饰整个类，描述Controller的作用
    2. @ApiOperation：描述一个类的一个方法，或者说一个接口
    3. @ApiParam：单个参数描述 @ApiModel：用对象来接收参数
    4. @ApiProperty：用对象接收参数时，描述对象的一个字段
    5. @ApiResponse：HTTP响应其中1个描述
    6. @ApiResponses：HTTP响应整体描述
    7. @ApiIgnore：使用该注解忽略这个API
    8. @ApiError ：发生错误返回的信息
    9. @ApiImplicitParam：一个请求参数
    10. @ApiImplicitParams：多个请求参数
  2. 描述控制器类
    1. swagger通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息的等等。代码如下：
package com.cyj.springboot.web;

import java.util.ArrayList;
import java.util.Collections;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PathVariable;
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.cyj.springboot.config.JsonResult;
import com.cyj.springboot.entity.User;

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

/**
 * 
 * @Description:
 * @ClassName: HelloWorldController.java
 * @author ChenYongJia
 * @Date 2018年8月11日 下午3:45:17
 * @Email 867647213@qq.com
 */
@RestController
public class UserController {

	// 创建线程安全的Map
	static Map<Integer, User> users = Collections.synchronizedMap(new HashMap<Integer, User>());

	/**
	 * 根据ID查询用户
	 * 
	 * @param id
	 * @return
	 */
	@ApiOperation(value = "获取用户详细信息", notes = "根据url的id来获取用户详细信息")
	@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Integer", paramType = "path")
	@RequestMapping(value = "user/{id}", method = RequestMethod.GET)
	public ResponseEntity<JsonResult> getUserById(@PathVariable(value = "id") Integer id) {
		JsonResult r = new JsonResult();
		try {
			User user = users.get(id);
			r.setResult(user);
			r.setStatus("ok");
		} catch (Exception e) {
			r.setResult(e.getClass().getName() + ":" + e.getMessage());
			r.setStatus("error");
			e.printStackTrace();
		}
		return ResponseEntity.ok(r);
	}

	/**
	 * 查询用户列表
	 * 
	 * @return
	 */
	@ApiOperation(value = "获取用户列表", notes = "获取用户列表")
	@RequestMapping(value = "users", method = RequestMethod.GET)
	public ResponseEntity<JsonResult> getUserList() {
		JsonResult r = new JsonResult();
		try {
			List<User> userList = new ArrayList<User>(users.values());
			r.setResult(userList);
			r.setStatus("ok");
		} catch (Exception e) {
			r.setResult(e.getClass().getName() + ":" + e.getMessage());
			r.setStatus("error");
			e.printStackTrace();
		}
		return ResponseEntity.ok(r);
	}

	/**
	 * 添加用户
	 * 
	 * @param user
	 * @return
	 */
	@ApiOperation(value = "创建用户", notes = "根据User对象创建用户")
	@ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
	@RequestMapping(value = "user", method = RequestMethod.POST)
	public ResponseEntity<JsonResult> add(@RequestBody User user) {
		JsonResult r = new JsonResult();
		try {
			users.put(user.getId(), user);
			r.setResult(user.getId());
			r.setStatus("ok");
		} catch (Exception e) {
			r.setResult(e.getClass().getName() + ":" + e.getMessage());
			r.setStatus("error");

			e.printStackTrace();
		}
		return ResponseEntity.ok(r);
	}

	/**
	 * 根据id删除用户
	 * 
	 * @param id
	 * @return
	 */
	@ApiOperation(value = "删除用户", notes = "根据url的id来指定删除用户")
	@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long", paramType = "path")
	@RequestMapping(value = "user/{id}", method = RequestMethod.DELETE)
	public ResponseEntity<JsonResult> delete(@PathVariable(value = "id") Integer id) {
		JsonResult r = new JsonResult();
		try {
			users.remove(id);
			r.setResult(id);
			r.setStatus("ok");
		} catch (Exception e) {
			r.setResult(e.getClass().getName() + ":" + e.getMessage());
			r.setStatus("error");

			e.printStackTrace();
		}
		return ResponseEntity.ok(r);
	}

	/**
	 * 根据id修改用户信息
	 * 
	 * @param user
	 * @return
	 */
	@ApiOperation(value = "更新信息", notes = "根据url的id来指定更新用户信息")
	@ApiImplicitParams({
			@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long", paramType = "path"),
			@ApiImplicitParam(name = "user", value = "用户实体user", required = true, dataType = "User") })
	@RequestMapping(value = "user/{id}", method = RequestMethod.PUT)
	public ResponseEntity<JsonResult> update(@PathVariable("id") Integer id, @RequestBody User user) {
		JsonResult r = new JsonResult();
		try {
			User u = users.get(id);
			u.setUsername(user.getUsername());
			u.setAge(user.getAge());
			users.put(id, u);
			r.setResult(u);
			r.setStatus("ok");
		} catch (Exception e) {
			r.setResult(e.getClass().getName() + ":" + e.getMessage());
			r.setStatus("error");

			e.printStackTrace();
		}
		return ResponseEntity.ok(r);
	}

	@ApiIgnore // 使用该注解忽略这个API
	@RequestMapping(value = "/hi", method = RequestMethod.GET)
	public String jsonTest() {
		return " hi you!";
	}

	/*
	 * @Api：修饰整个类，描述Controller的作用
	 * 
	 * @ApiOperation：描述一个类的一个方法，或者说一个接口
	 * 
	 * @ApiParam：单个参数描述
	 * 
	 * @ApiModel：用对象来接收参数
	 * 
	 * @ApiProperty：用对象接收参数时，描述对象的一个字段
	 * 
	 * @ApiResponse：HTTP响应其中1个描述
	 * 
	 * @ApiResponses：HTTP响应整体描述
	 * 
	 * @ApiIgnore：使用该注解忽略这个API
	 * 
	 * @ApiError ：发生错误返回的信息
	 * 
	 * @ApiImplicitParam：一个请求参数
	 * 
	 * @ApiImplicitParams：多个请求参数
	 */

}

其中SpringMVC4.0以上的版本支持@RequestMapping的简写方式，如上例代码中的@RequestMapping可简写为@GetMapping(“user/{id}”)即可。

编写Swagger配置类Swagger2,扫描SpringMVC控制器

在配置类中指定将要扫描的springmvc控制器的包，代码如下：

package com.cyj.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;

/**
 * 
 * @Description: Swagger配置类
 * @ClassName: Swagger2Config.java
 * @author ChenYongJia
 * @Date 2018年8月11日 下午4:00:28
 * @Email 867647213@qq.com
 */
@Configuration
public class Swagger2Config {
	@Bean
	public Docket createRestApi() {
		// 扫描控制器中Swagger2的注解
		return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
				.apis(RequestHandlerSelectors.basePackage("com.cyj.springboot.web")).paths(PathSelectors.any()).build();
	}

	// API描述信息
	private ApiInfo apiInfo() {
		return new ApiInfoBuilder().title("springboot利用swagger构建api文档")
				.description("简单优雅的文章风格，https://blog.csdn.net/mrs_chens/category_8935373.html")
				.termsOfServiceUrl("https://blog.csdn.net/mrs_chens/category_8935373.html").version("1.0").build();
	}

}

SpringBoot启动类上开启Swagger2

最后需要在启动类上，加上注解@EnableSwagger2来开启Swagger，代码如下：

package com.cyj.springboot;

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

import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * 
 * @Description: Spring Boot 应用启动类
 * @ClassName: Application.java
 * @author ChenYongJia
 * @Date 2018年8月11日 下午3:59:36
 * @Email 867647213@qq.com
 */
@EnableSwagger2
@SpringBootApplication
public class Application {

	public static void main(String[] args) {
		// 程序启动入口
		// 启动嵌入式的 Tomcat 并初始化 Spring 环境及其各 Spring 组件
		SpringApplication.run(Application.class, args);
	}
}

至此，Springboot与swagger2的集成步骤已经完成，接下来，我们来测试一下，启动SpringBoot项目，访
问路径： http://localhost:8080/swagger-ui.html ，效果图如下：

在这里插入图片描述

完整代码地址Github（如果有用点个star呗） https://github.com/chenxiban/BlogCaseSet.git

启动测试一下，就交给你自己了

最后

  • 更多参考精彩博文请看这里：《陈永佳的博客》

  • 喜欢博主的小伙伴可以加个关注、点个赞哦，持续更新嘿嘿！

版权声明：本文内容由互联网用户自发贡献，该文观点仅代表作者本人。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如发现本站有涉嫌侵权/违法违规的内容， 请发送邮件至 举报，一经查实，本站将立刻删除。

文章由极客之音整理，本文链接：https://www.bmabk.com/index.php/post/97624.html

赞 (0)
小半的头像小半
0 0

相关推荐

极客之音——专业性很强的中文编程技术网站，欢迎收藏到浏览器，订阅我们！