SpringBoot2.x系列教程13--SpringBoot中整合Swagger生成接口的在线文档

简介: 前言在前一章节中,壹哥 带大家学习了如何基于RESTful来设计我们的Web接口,后端团队把接口设计出来了,前端团队就可以直接调用了吗?这里我们想一下,前端团队怎么知道后端团队设计的接口长啥样呢?前端调用接口时,该传递什么样的参数?返回值什么含义?接口地址在哪?......这些信息前端团队统统不知道啊,因为接口是后端写的!所以前后端之间在进行接口调用时,是不是还需要有个可以展示暴露接口的东西呢?这就是接口文档了!今天 壹哥 就带大家学习一个比较牛逼的在线接口文档工具--Swagger!一. Swagger2简介我们可以在Spring Boot中构建RESTful风格的API接口,

前言

在前一章节中,壹哥 带大家学习了如何基于RESTful来设计我们的Web接口,后端团队把接口设计出来了,前端团队就可以直接调用了吗?这里我们想一下,前端团队怎么知道后端团队设计的接口长啥样呢?前端调用接口时,该传递什么样的参数?返回值什么含义?接口地址在哪?......这些信息前端团队统统不知道啊,因为接口是后端写的!

所以前后端之间在进行接口调用时,是不是还需要有个可以展示暴露接口的东西呢?这就是接口文档了!

今天 壹哥 就带大家学习一个比较牛逼的在线接口文档工具--Swagger!

一. Swagger2简介

我们可以在Spring Boot中构建RESTful风格的API接口,这样做的目的通常都是由于多终端的原因,这些终端会共用很多底层业务逻辑,因此我们会抽象出这样一层来同时服务于多个移动端或者Web前端。

那么此时我们的RESTful API就有可能要面对多个开发人员或多个开发团队:IOS开发、Android开发或是Web开发等。为了减少与其他团队平时开发期间的频繁沟通成本,传统做法我们会创建一份RESTful API文档来记录所有接口细节,然而这样的做法有以下几个问题:

1️⃣. 由于接口众多,并且细节复杂(需要考虑不同的HTTP请求类型、HTTP头部信息、HTTP请求内容等),高质量地创建这份文档本身就是件非常吃力的事;

2️⃣. 随着时间推移,不断修改接口实现的时候都必须同步修改接口文档,而文档与代码又处于两个不同的媒介,除非有严格的管理机制,不然很容易导致不一致现象。

为了解决上面的问题,我们可以利用Swagger2,它可以轻松的被整合到SpringBoot中,并与SpringMVC程序配合组织出强大RESTful API文档。它既可以减少我们创建文档的工作量,同时说明内容又整合入实现代码中,让维护文档和修改代码整合为一体,可以让我们在修改代码逻辑的同时方便的修改文档说明。

另外Swagger2也提供了强大的页面测试功能,来调试每个RESTful API,具体效果如下图所示:

二. Swagger2具体实现

了解完Swagger2的基本理论知识,接下来 壹哥 就带各位进行代码实操,看看如何生成Swagger2的在线文档。

1. 创建一个新的web模块

首先我们还是要创建一个web项目,具体创建过程请参考之前的章节。

2. 在pom文件中添加依赖

我们在原有的依赖基础上,新增一个swagger2的依赖包spring-fox。

<dependencies><!--web启动器是与SpringMVC相关的依赖--><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><!--springfox的核心jar包--><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.7.0</version></dependency><!--springfox-ui的jar包(里面包含了swagger的界面静态文件)--><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>2.7.0</version></dependency></dependencies>

3. 创建SwaggerConfig配置类

创建一个单独的package,在里面新建一个SwaggerConfig类。

packagecom.yyg.boot.config;
importorg.springframework.context.annotation.Bean;
importorg.springframework.context.annotation.ComponentScan;
importorg.springframework.context.annotation.Configuration;
importspringfox.documentation.builders.ApiInfoBuilder;
importspringfox.documentation.builders.RequestHandlerSelectors;
importspringfox.documentation.service.ApiInfo;
importspringfox.documentation.service.Contact;
importspringfox.documentation.spi.DocumentationType;
importspringfox.documentation.spring.web.plugins.Docket;
importspringfox.documentation.swagger2.annotations.EnableSwagger2;
/*** @Author 一一哥Sun* @Date Created in 2020/5/13* @Description Description*/@Configuration@EnableSwagger2//@ComponentScan(basePackages = "com.yyg.boot.web")publicclassSwagger2Config {
@BeanpublicDocketapi() {
returnnewDocket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .apis(RequestHandlerSelectors.basePackage("com.yyg.boot.web"))
//.paths(PathSelectors.any())                .build()
                .apiInfo(apiInfo());
    }
privateApiInfoapiInfo() {
returnnewApiInfoBuilder()
                .title("XXX项目接口文档")
                .description("XXX项目接口测试")
                .version("1.0.1")
                .contact(newContact("一一哥","https://yiyige.blog.csdn.net/","2312119590"))
                .termsOfServiceUrl("")
                .license("")
                .licenseUrl("")
                .build();
    }
}

API说明:

1️⃣. 通过@Configuration注解,使得该类成为配置类,Spring可以加载该配置;

2️⃣. 再通过@EnableSwagger2注解来启用Swagger2;

3️⃣. 通过createRestApi()方法创建Docket的Bean之后,apiInfo()方法用来创建该Api的基本信息(这些基本信息会展现在文档页面中)。select()方法返回一ApiSelectorBuilder实例,用来控制哪些接口暴露给 Swagger来展现。

4️⃣. 为了增强用户友好性,我们通常需要自己增加一些说明来丰富文档内容。如下所示,我们通过@ApiOperation注解来给API增加说明、通过@ApiImplicitParams、@ApiImplicitParam注解来给参数增加说明。

4. 创建User实体类

封装一个User实体类,用于封装用户信息。

packagecom.yyg.boot.domain;
importio.swagger.annotations.ApiModel;
importio.swagger.annotations.ApiModelProperty;
importlombok.Data;
importjava.io.Serializable;
/*** @Author 一一哥Sun* @Date Created in 2020/5/13* @Description Description*/@Data@ApiModelpublicclassUserimplementsSerializable {
@ApiModelProperty("用户id")
privateLongid;
@ApiModelProperty("用户姓名")
privateStringname;
@ApiModelProperty("用户年龄")
privateIntegerage;
}

5. 创建Controller接口

然后我们创建一个Controller接口,在该接口上添加Swagger相关注解,这里每个注解的作用,我都在代码的注释中做了说明。

packagecom.syc.boot.web;
importcom.syc.boot.domain.User;
importio.swagger.annotations.ApiImplicitParam;
importio.swagger.annotations.ApiImplicitParams;
importio.swagger.annotations.ApiOperation;
importorg.springframework.web.bind.annotation.*;
importjava.util.*;
@RestController// 通过这里配置使下面的映射都在/users下@RequestMapping(value="/users")
publicclassUserController {
// 创建线程安全的MapstaticMap<Long, User>users=Collections.synchronizedMap(newHashMap<>());
// 处理GET请求,用来获取用户列表.// 可以通过@RequestParam获取从页面中传递进来的查询条件或者翻页信息等参数.@ApiOperation(value="获取用户列表", notes="")
@RequestMapping(value="/", method=RequestMethod.GET)
publicList<User>getUserList() {
returnnewArrayList<>(users.values());
    }
// 处理POST请求,用来创建User.// 除了@ModelAttribute绑定参数之外,还可以通过@RequestParam从页面中传递参数.@ApiOperation(value="创建用户", notes="根据User对象创建用户")
@ApiImplicitParam(name="user", value="用户详细实体user", required=true, dataType="User")
@RequestMapping(value="/", method=RequestMethod.POST)
publicStringaddUser(@RequestBodyUseruser) {
users.put(user.getId(), user);
System.out.println("user==="+users.get(user.getId()));
return"success";
    }
// 处理GET请求,用来获取url中id值的User信息;// url中的id可通过@PathVariable绑定到函数的参数中.@ApiOperation(value="获取用户详细信息", notes="根据url的id来获取用户详细信息")
@ApiImplicitParam(name="id", value="用户ID", required=true, dataType="Long")
@RequestMapping(value="/{id}", method=RequestMethod.GET)
publicUsergetUser(@PathVariableLongid) {
returnusers.get(id);
    }
// 处理PUT请求,用来更新User信息.@ApiOperation(value="更新用户详细信息", notes="根据url的id来指定更新对象,并根据传过来的user信息来更新用户详细信息")
@ApiImplicitParams({
@ApiImplicitParam(name="id", value="用户ID", required=true, dataType="Long"),
@ApiImplicitParam(name="user", value="用户详细实体user", required=true, dataType="User")
    })
@RequestMapping(value="/{id}", method=RequestMethod.PUT)
publicStringupdateUser(@PathVariableLongid, @RequestBodyUseruser) {
Useru=users.get(id);
u.setName(user.getName());
u.setAge(user.getAge());
users.put(id, u);
return"success";
    }
// 处理DELETE请求,用来删除User@ApiOperation(value="删除用户", notes="根据url的id来指定删除对象")
@ApiImplicitParam(name="id", value="用户ID", required=true, dataType="Long")
@RequestMapping(value="/{id}", method=RequestMethod.DELETE)
publicStringdeleteUser(@PathVariableLongid) {
users.remove(id);
return"success";
    }
}

6. 创建入口类

最后我们还是创建一个入口类,用于启动项目。

packagecom.yyg.boot;
importorg.springframework.boot.SpringApplication;
importorg.springframework.boot.autoconfigure.SpringBootApplication;
/*** @Author 一一哥Sun* @Date Created in 2020/5/13* @Description Description*/@SpringBootApplicationpublicclassRestfulApplication {
publicstaticvoidmain(String[] args){
SpringApplication.run(RestfulApplication.class,args);
    }
}

三. 启动项目,运行测试

1. 访问在线文档

启动项目后,我们访问地址:[项目访问地址]/swagger-ui.html

例如: http://localhost:8080/swagger-ui.html

这时就会发现已经成功的创建了一个Swagger在线文档,我们的每个Web接口都在该文档中展示了出来。

2. 在文档中进行接口测试

Swagger不仅可以展示接口文档的内容,也可以像Postman那样进行简单的接口测试。

至于Swagger还有哪些宝藏功能,大家自行发掘吧。

结语

至此,壹哥 就带大家实现了Swagger在线接口文档了,这样前后端之间配合开发时就不用天天用QQ来沟通接口文档的内容了。

今日小作业:

请生成自己的学生管理系统在线接口文档,并在文档中测试学生信息的增删改查接口是否良好。

相关文章
|
20天前
|
API
支付系统38-----支付宝支付---统一收单线下交易查询 第一步下单------》发起支付请求,登录,确认支付,查单接口开发,swagger接口全部呈现,
支付系统38-----支付宝支付---统一收单线下交易查询 第一步下单------》发起支付请求,登录,确认支付,查单接口开发,swagger接口全部呈现,
|
17天前
|
数据可视化 Java API
Spring Boot与Swagger的集成
Spring Boot与Swagger的集成
|
17天前
|
Java API 开发者
在Spring Boot中集成Swagger API文档
在Spring Boot中集成Swagger API文档
|
7天前
|
安全 Java API
Nest.js 实战 (三):使用 Swagger 优雅地生成 API 文档
这篇文章介绍了Swagger,它是一组开源工具,围绕OpenAPI规范帮助设计、构建、记录和使用RESTAPI。文章主要讨论了Swagger的主要工具,包括SwaggerEditor、SwaggerUI、SwaggerCodegen等。然后介绍了如何在Nest框架中集成Swagger,展示了安装依赖、定义DTO和控制器等步骤,以及如何使用Swagger装饰器。文章最后总结说,集成Swagger文档可以自动生成和维护API文档,规范API标准化和一致性,但会增加开发者工作量,需要保持注释和装饰器的准确性。
Nest.js 实战 (三):使用 Swagger 优雅地生成 API 文档
|
9天前
|
SQL Java 数据库
实时计算 Flink版产品使用问题之Spring Boot集成Flink可以通过什么方式实现通过接口启动和关闭Flink程序
实时计算Flink版作为一种强大的流处理和批处理统一的计算框架,广泛应用于各种需要实时数据处理和分析的场景。实时计算Flink版通常结合SQL接口、DataStream API、以及与上下游数据源和存储系统的丰富连接器,提供了一套全面的解决方案,以应对各种实时计算需求。其低延迟、高吞吐、容错性强的特点,使其成为众多企业和组织实时数据处理首选的技术平台。以下是实时计算Flink版的一些典型使用合集。
|
20天前
|
Java
软件开发常用之SpringBoot文件下载接口编写(下),Vue+SpringBoot文件上传下载预览,服务器默认上传是1M,可以调节,调节文件上传大小写法,图片预览,如何预览后下次还能看到,预览写法
软件开发常用之SpringBoot文件下载接口编写(下),Vue+SpringBoot文件上传下载预览,服务器默认上传是1M,可以调节,调节文件上传大小写法,图片预览,如何预览后下次还能看到,预览写法
|
21天前
|
文字识别 Java Python
文本,文识10,springBoot提供RestTemplate以调用Flask OCR接口,调用flask实现ocr接口,用paddleocr进行图片识别云服务技术,单个paddleocr接口有影响
文本,文识10,springBoot提供RestTemplate以调用Flask OCR接口,调用flask实现ocr接口,用paddleocr进行图片识别云服务技术,单个paddleocr接口有影响
|
21天前
|
文字识别 Java
文本,文字识别07,SpringBoot服务开发-入参和返回值,编写接口的时候,要注意识别的文字返回的是多行,因此必须是List集合,Bean层,及实体类的搭建
文本,文字识别07,SpringBoot服务开发-入参和返回值,编写接口的时候,要注意识别的文字返回的是多行,因此必须是List集合,Bean层,及实体类的搭建
|
21天前
|
文字识别 Java Spring
文本,文字识别,SpringBoot服务开发,SpringBoot如何提供上传服务,接口的设计,它做了将Base64重新转为图片,SpringBoot的应用实例,项目基础搭建
文本,文字识别,SpringBoot服务开发,SpringBoot如何提供上传服务,接口的设计,它做了将Base64重新转为图片,SpringBoot的应用实例,项目基础搭建
|
19天前
|
JSON 数据格式
MysbatisPlus-核心功能-IService开发基础业务接口,MysbatisPlus_Restful风格,新增@RequestBody指定是为了接收Json数据的,使用swagger必须注解
MysbatisPlus-核心功能-IService开发基础业务接口,MysbatisPlus_Restful风格,新增@RequestBody指定是为了接收Json数据的,使用swagger必须注解