使用Spring BootSwagger快速构建REST API并生成优美的API文档

本文主要是介绍使用Spring BootSwagger快速构建REST API并生成优美的API文档,希望对大家解决编程问题提供一定的参考价值,需要的开发者们随着小编来一起学习吧!

使用Spring Boot&Swagger快速构建REST API并生成优美的API文档


通常我们要构建API 服务,自然少不了文档,但由于API与文档的分离使得我们每次对API进行的更改都需要去同步文档,稍有纰漏难免就会出现调用的异常,而编写、同步文档通常是比较繁琐无趣的事。现在得益于Spring Boot 与Swagger,我们不但可以极速的搭建REST、RESTful风格的API服务并且还可以生成优美、强大的在线或离线API文档。

  • 引入Maven依赖
    <parent><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-parent</artifactId><version>1.4.1.RELEASE</version></parent><dependencies><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.2.2</version></dependency><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>2.2.2</version></dependency></dependencies>
  • 创建Application主类
package example;//注意包结构
@SpringBootApplication
public class Application {public static void main(String[] args) throws Exception {SpringApplication.run(Application.class, args);}
}
  • 创建Swagger配置类
package example.config;//注意包结构
@Configuration
@EnableSwagger2
public class Swagger2Configuration {@Beanpublic Docket buildDocket() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(buildApiInf()).select().apis(RequestHandlerSelectors.basePackage("example.web.controller"))//要扫描的API(Controller)基础包.paths(PathSelectors.any()).build();}private ApiInfo buildApiInf() {return new ApiInfoBuilder().title("Spring Boot中使用Swagger2 UI构建API文档").contact("土豆").version("1.0").build();}
}
  • 创建RestController 构建一个简单计算服务API
package example.web.controller;//注意包结构
@Api(value = "计算服务",description="简单的计算服务,提供加减乘除运算API")
@RestController
@RequestMapping("/compute")
public class ComputeController {@ApiOperation("加法运算")@PostMapping("/add")public Double add(@RequestParam Double a,  @RequestParam Double b) {return a + b;}@ApiOperation("减法运算")@PostMapping("/sub")public Double sub(@RequestParam Double a,  @RequestParam Double b) {return a - b;}@ApiOperation("乘法运算")@PostMapping("/mul")public Double mul(@RequestParam Double a,  @RequestParam Double b) {return a * b;}@ApiOperation("除法运算")@PostMapping("/div")public Double div(@ApiParam("被除数")@RequestParam Double a, @ApiParam("除数")@RequestParam   Double b) {return a / b;}
}

@Api注解用来表述该服务的信息,如果不使用则显示类名称.
@ApiOperation注解用于表述接口信息
@ApiParam注解用于描述接口的参数

通过上面几步我们已经成功构建了一个具备加减乘除的计算服务API,并且已经拥有一份不错的在线文档了,现在我们来启动它,执行mvn spring-boot:run,或直接运行Application.main()

启动成功后,访问http://localhost:8080/swagger-ui.html,便可以看到我们刚才构建的计算服务的API文档了。


swagger-ui


Swagger UI不仅仅是文档,还提供了在线API调试的功能,我们可以调试下我们的除法运算API。


swagger-ui


点击Try it out!后可以看到我们成功的调用了除法运算API并获得了正确的响应。


swagger-ui
  • 创建RESTful 风格的API及文档

下面我们以用户的增删改查服务为例

1.创建Model

package example.model;//注意包结构
public class User {private Long id;private String username;private Integer age;//省略getter、setter方法}

2.创建RestController

package example.web.controller;//注意包结构
@RestController
@RequestMapping("/user")
@Api(value = "用户服务",description = "提供RESTful风格API的用户的增删改查服务")
public class UserController {//模拟DAO层private final Map<Long, User> repository = new HashMap<Long, User>();@PostMapping@ApiOperation("添加用户")public Boolean add(@RequestBody User user) {repository.put(user.getId(), user);return true;}@DeleteMapping("/{id}")@ApiOperation("通过ID删除用户")public Boolean delete(@PathVariable Long id) {repository.remove(id);return true;}@PutMapping@ApiOperation("更新用户")public Boolean update(@RequestBody User user) {repository.put(user.getId(), user);return true;}@GetMapping("/{id}")@ApiOperation("通过ID查询用户")public User findById(@PathVariable Long id) {return repository.get(id);}
}

这里说点题外话,@GetMapping,@PostMapping,@PutMapping,@DeleteMapping 等注解是Spring MVC 4.3X版本添加的新注解,它们是对@RequestMapping注解的简化封装。

好了,我们重新启动下Application,再次访问http://localhost:8080/swagger-ui.html,用户服务的RESTful API文档也已生成。


swagger-ui

我们来尝试调用添加用户API增加一位用户


swagger-ui


成功后,我们调用查询API,来进行查询看时候可以返回正确的JSON数据。


swagger-ui
  • 为Model(JSON)添加注释

为了使API的调用者能够清晰的知道请求和响应的Model中各字段的具体含义,我们需要对其添加一些简单的注释,而Swagger也为我们提供了相应的注解比如@ApiModel、@ApiModelProperty来帮助我们解释我们的Model,下面就是最简单的使用例子,详细用法及更多相关注解点我查看~

@ApiModel("User(用户模型)")
public class User {@ApiModelProperty("ID")private Long id;@ApiModelProperty("用户名")private String username;@ApiModelProperty("年龄")private Integer age;//省略getter、setter方法
}

swagger-ui

这一切是不是很简单?从开发API到构建高逼格的API文档完全可以用极速来形容。当然,本文也只是展现了Spring Boot + Swagger的冰山一角,要了解更多细节那就快去翻阅官方文档吧~

本示例完整代码的GIT地址点击我~
Swagger-Core文档点击我~
SpringFox文档点击我~
Spring Boot 文档点击我~
还不错的Spring Boot系列教程点击我~

这篇关于使用Spring BootSwagger快速构建REST API并生成优美的API文档的文章就介绍到这儿,希望我们推荐的文章对编程师们有所帮助!


原文地址:
本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如若转载,请注明出处:http://www.chinasem.cn/article/630212

相关文章

使用Python实现Windows系统垃圾清理

《使用Python实现Windows系统垃圾清理》Windows自带的磁盘清理工具功能有限,无法深度清理各类垃圾文件,所以本文为大家介绍了如何使用Python+PyQt5开发一个Windows系统垃圾... 目录一、开发背景与工具概述1.1 为什么需要专业清理工具1.2 工具设计理念二、工具核心功能解析2.

Linux系统之stress-ng测压工具的使用

《Linux系统之stress-ng测压工具的使用》:本文主要介绍Linux系统之stress-ng测压工具的使用,具有很好的参考价值,希望对大家有所帮助,如有错误或未考虑完全的地方,望不吝赐教... 目录一、理论1.stress工具简介与安装2.语法及参数3.具体安装二、实验1.运行8 cpu, 4 fo

Maven项目中集成数据库文档生成工具的操作步骤

《Maven项目中集成数据库文档生成工具的操作步骤》在Maven项目中,可以通过集成数据库文档生成工具来自动生成数据库文档,本文为大家整理了使用screw-maven-plugin(推荐)的完... 目录1. 添加插件配置到 pom.XML2. 配置数据库信息3. 执行生成命令4. 高级配置选项5. 注意事

Java使用MethodHandle来替代反射,提高性能问题

《Java使用MethodHandle来替代反射,提高性能问题》:本文主要介绍Java使用MethodHandle来替代反射,提高性能问题,具有很好的参考价值,希望对大家有所帮助,如有错误或未考虑... 目录一、认识MethodHandle1、简介2、使用方式3、与反射的区别二、示例1、基本使用2、(重要)

使用C#删除Excel表格中的重复行数据的代码详解

《使用C#删除Excel表格中的重复行数据的代码详解》重复行是指在Excel表格中完全相同的多行数据,删除这些重复行至关重要,因为它们不仅会干扰数据分析,还可能导致错误的决策和结论,所以本文给大家介绍... 目录简介使用工具C# 删除Excel工作表中的重复行语法工作原理实现代码C# 删除指定Excel单元

Java实现本地缓存的常用方案介绍

《Java实现本地缓存的常用方案介绍》本地缓存的代表技术主要有HashMap,GuavaCache,Caffeine和Encahche,这篇文章主要来和大家聊聊java利用这些技术分别实现本地缓存的方... 目录本地缓存实现方式HashMapConcurrentHashMapGuava CacheCaffe

SpringBoot整合Sa-Token实现RBAC权限模型的过程解析

《SpringBoot整合Sa-Token实现RBAC权限模型的过程解析》:本文主要介绍SpringBoot整合Sa-Token实现RBAC权限模型的过程解析,本文给大家介绍的非常详细,对大家的学... 目录前言一、基础概念1.1 RBAC模型核心概念1.2 Sa-Token核心功能1.3 环境准备二、表结

MySQL 事务的概念及ACID属性和使用详解

《MySQL事务的概念及ACID属性和使用详解》MySQL通过多线程实现存储工作,因此在并发访问场景中,事务确保了数据操作的一致性和可靠性,下面通过本文给大家介绍MySQL事务的概念及ACID属性和... 目录一、什么是事务二、事务的属性及使用2.1 事务的 ACID 属性2.2 为什么存在事务2.3 事务

eclipse如何运行springboot项目

《eclipse如何运行springboot项目》:本文主要介绍eclipse如何运行springboot项目问题,具有很好的参考价值,希望对大家有所帮助,如有错误或未考虑完全的地方,望不吝赐教... 目js录当在eclipse启动spring boot项目时出现问题解决办法1.通过cmd命令行2.在ecl

Java中的Closeable接口及常见问题

《Java中的Closeable接口及常见问题》Closeable是Java中的一个标记接口,用于表示可以被关闭的对象,它定义了一个标准的方法来释放对象占用的系统资源,下面给大家介绍Java中的Clo... 目录1. Closeable接口概述2. 主要用途3. 实现类4. 使用方法5. 实现自定义Clos