SpringBoot整合Swagger实战
源码地址:https://github.com/laolunsi/spring-boot-examples
目前SpringBoot常被用于开发Java Web应用,特别是前后端分离项目。为方便前后端开发人员进行沟通,我们在SpringBoot引入了Swagger。
Swagger作用于接口,让接口数据可视化,尤其适用于Restful APi
本节分两部分介绍,第一部分是SpringBoot引入Swagger的两种方式,第二部分是详细介绍在Web接口上应用Swagger的注解。
本篇文章使用SpringBoot 2.1.10.RELEASE和springfox-swagger 2.9.2
一、SpringBoot引入Swagger的两种方式
目前SpringBoot有两种使用Swagger的方式:
- 引入swagger原生依赖
springfox-swagger2
和springfox-swagger2-ui
- 引入国内Spring4All社区开发的依赖
swagger-spring-boot-starter
Spring4All出品的依赖采取配置文件的方式进行配置,而原生依赖是通过java config类来设置的。
1.1 原生配置Swagger
maven依赖:
<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>
swagger配置类:
/**
* swagger2配置类
*/
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.example"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("基于Swagger构建的Rest API文档")
.description("更多请咨询服务开发者eknown")
.contact(new Contact("空夜", "http://www.eknown.cn", "eknown@163.com"))
.termsOfServiceUrl("http://www.eknown.com")
.version("1.0")
.build();
}
}
从这里可以看出Swagger的一个缺点:无法通过SpringBoot的配置文件进行配置,所以配置并不能灵活转变。
spring4all社区出品的swagger-spring-boot-starter可以解决这个问题。
1.2 基于spring4all配置swagger
Spring4All社区的博主程序猿DD和小火两个人开发了Spring Boot Starter Swagger,目前已经在maven官方仓库上线了。
选择第一个,引入该依赖:
<dependency>
<groupId>com.spring4all</groupId>
<artifactId>swagger-spring-boot-starter</artifactId>
<version>1.9.0.RELEASE</version>
</dependency>
这种方式的Swagger配置是通过application配置文件进行的。下面给出一个示例:
server:
port: 8106
swagger:
base-path: /**
base-package: 'com.example'
title: 'spring-boot-swagger-demo'
description: '基于Swagger构建的SpringBoot RESTApi 文档'
version: '1.0'
contact:
name: '空夜'
url: 'http://www.eknown.cn'
email: 'eknown@163.com'
二、应用Swagger构建接口可视化
2.1 Controller类添加Swagger注解
下面给一个简单的示例:
@Api(tags = "用户管理")
@RestController
@RequestMapping(value = "user")
public class UserController {
// 模拟数据库存储的用户
private static Map<Integer, User> userMap;
static {
userMap = new ConcurrentHashMap<>();
User user = new User(0, "admin", true, new Date());
userMap.put(user.getId(), user);
}
@ApiOperation("列表查询")
@GetMapping(value = "")
public List<User> list() {
return new ArrayList<>(userMap.values());
}
@ApiOperation(value = "获取用户详细信息", notes = "路径参数ID")
@GetMapping(value = "{id}")
public User detail(@PathVariable Integer id) {
return userMap.get(id);
}
@ApiOperation(value = "新增或更新用户信息", notes = "insert和update共用"
, response = User.class)
@PostMapping(value = "")
public User add(@RequestBody User user) {
if (user == null || user.getId() == null || !StringUtils.isEmpty(user.getName())
|| userMap.containsKey(user.getId())) {
return null;
}
user.setUpdateTime(new Date());
userMap.put(user.getId(), user);
return user;
}
@ApiOperation(value = "删除用户")
@DeleteMapping(value = "{id}")
public Boolean delete(@ApiParam(name = "用户ID", required = true, example = "100") @PathVariable Integer id) {
if (userMap.containsKey(id)) {
userMap.remove(id);
return true;
}
return false;
}
}
2.2 参数实体类添加Swagger注解
实体类也需要添加一些注解,以便前端开发人员确定参数的意义、类型、示例等。
@ApiModel(description = "用户类")
public class User {
@ApiModelProperty(value = "ID", example = "100")
private Integer id;
@ApiModelProperty(value = "姓名", example = "laolunsi")
private String name;
@ApiModelProperty(value = "是否启用", example = "1")
private Boolean enable;
@ApiModelProperty("更新时间")
private Date updateTime;
public User(Integer id, String name, Boolean enable, Date updateTime) {
this.id = id;
this.name = name;
this.enable = enable;
this.updateTime = updateTime;
}
// ... ignore getter and setter methods
}
2.3 测试
启动项目,访问http://localhost:port/swagger-ui.html
如果存在server.servlet.context-path配置,那么访问地址是http://localhost:port/context-path/swagger-ui.html
这样,接口就一目了然了,swagger还支持在线测试接口,与postman的作用类似。
好,到目前为止,我们已经成功在SpringBoot项目中整合了Swagger,这样前后端开发对接就有了标准!
SpringBoot整合Swagger实战的更多相关文章
- springboot集成swagger实战(基础版)
1. 前言说明 本文主要介绍springboot整合swagger的全过程,从开始的swagger到Knife4j的进阶之路:Knife4j是swagger-bootstarp-ui的升级版,包括一些 ...
- SpringBoot 整合swagger
springBoot 整合swagger 1.pom.xml 配置 <dependency> <groupId>io.springfox</groupId> < ...
- SpringBoot整合Swagger和Actuator
前言 本篇文章主要介绍的是SpringBoot整合Swagger(API文档生成框架)和SpringBoot整合Actuator(项目监控)使用教程. SpringBoot整合Swagger 说明:如 ...
- 【SpringBoot | Swagger】SpringBoot整合Swagger
SpringBoot整合Swagger 1. 什么是Swagger Swagger 是一个规范和完整的框架,用于生成.描述.调用和可视化 RESTful 风格的 Web 服务.简单说就是项目跑起来了, ...
- springboot整合swagger。完爆前后端调试
web接口开发时在调试阶段最麻烦的就是参数调试,前端需要咨询后端.后端有时候自己也不是很了解.这时候就会造成调试一次接口就需要看一次代码.Swagger帮我们解决对接的麻烦 springboot接入s ...
- springboot整合elasticJob实战(纯代码开发三种任务类型用法)以及分片系统,事件追踪详解
一 springboot整合 介绍就不多说了,只有这个框架是当当网开源的,支持分布式调度,分布式系统中非常合适(两个服务同时跑不会重复,并且可灵活配置分开分批处理数据,贼方便)! 这里主要还是用到zo ...
- SpringBoot 整合 MongoDB 实战介绍
一.介绍 在前面的文章中,我们详细的介绍了 MongoDB 的配置和使用,如果你对 MongoDB 还不是很了解,也没关系,在 MongoDB 中有三个比较重要的名词:数据库.集合.文档! 数据库(D ...
- SpringBoot整合Swagger测试api构建
@Author:SimpleWu 什么是Swagger? Swagger是什么:THE WORLD'S MOST POPULAR API TOOLING 根据官网的介绍: Swagger Inspec ...
- 【FastDFS】SpringBoot整合FastDFS实战,我只看这一篇!!
写在前面 在<[FastDFS]小伙伴们说在CentOS 8服务器上搭建FastDFS环境总报错?>和<[FastDFS]面试官:如何实现文件的大规模分布式存储?(全程实战)> ...
随机推荐
- CentOS7 Redis5.0.5环境搭建
CentOS7 Redis5.0.5环境搭建 1基本环境配置 CentOS Linux release 7.6.1810 (Core) redis 5.0.5 1.下载解压redis.通过wget在官 ...
- Python多任务之进程
Process多进程 进程的概念 程序是没有运行的代码,静态的: 进程是运行起来的程序,进程是一个程序运行起来之后和资源的总称: 程序只有一个,但同一份程序可以有多个进程:例如,电脑上多开QQ: 程序 ...
- Rust入坑指南:核心概念
如果说前面的坑我们一直在用小铲子挖的话,那么今天的坑就是用挖掘机挖的. 今天要介绍的是Rust的一个核心概念:Ownership.全文将分为什么是Ownership以及Ownership的传递类型两部 ...
- A-03 牛顿法和拟牛顿法
目录 牛顿法和拟牛顿法 一.牛顿法详解 1.1 无约束最优化问题 1.2 牛顿法迭代公式 1.3 牛顿法和梯度下降法 二.牛顿法流程 2.1 输入 2.2 输出 2.3 流程 三.拟牛顿法简介 更新. ...
- 重构网页过程中的小tips
1.display为inline-block的元素可以使用virtical-align:middle来使得元素垂直居中对齐 2.在一些按钮标签或者mark标签中,如果文本内容确定不会改变长度的话,可以 ...
- e课表项目第二次冲刺周期第十天
昨天完成了什么? 昨天还有一天第一次冲刺周期就结束了,我们的工作也接近尾声了,所以今天我利用之前的方法,完成了对监听的设置,以及对修改界面的编写,可以实现相应的删除和修改的功能,然后我和我们组的成员商 ...
- python常用算法学习(4)——数据结构
数据结构简介 1,数据结构 数据结构是指相互之间存在着一种或多种关系的数据元素的集合和该集合中数据元素之间的关系组成.简单来说,数据结构就是设计数据以何种方式组织并存贮在计算机中.比如:列表,集合与字 ...
- 最新打赏正版V15微信视频打赏源码 带(百倍)暗雷 N秒试看 自动切换域名 自动防封
免签支付域名防封随机跳转盒子推广设置试看N秒百倍 平台搭建:乌龟-源码科技QQ:64430146 全新版本 V15打赏版本功能介绍: 特别注意: 新增加功能!!!! 1.包括V14所有功能(除个别因优 ...
- Java学习笔记之基础语法(顺序,条件,循环语句)
顺序结构:自上而下 条件分支选择结构: if条件语句 1,一旦某一个分支确定执行以后,其他分支就不会执行.if后面的条件必须是boolean类型 2,if 后面如果不加大括号,默认相邻的下一 ...
- SpringBoot:2.SpringBoot整合Thymeleaf模板引擎渲染web视图
在Web开发过程中,Spring Boot可以通过@RestController来返回json数据,那如何渲染Web页面?Spring Boot提供了多种默认渲染html的模板引擎,主要有以下几种: ...