前言

快过年了,不知道你们啥时候放年假,忙不忙。反正我是挺闲的,所以有时间写 blog。今天给你们带来 SpringBoot 集成 Swagger2 的教程。

什么是 Swagger2

Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

为什么使用 Swagger2 ?

相信刚开始不熟悉 web 开发的时候,大家都有手写 Api 文档的时候。而手写 Api 文档主要有以下几个痛点:

  1. 文档需要更新的时候,需要再次发送一份给前端,也就是文档更新交流不及时。
  2. 接口返回结果不明确。
  3. 不能直接在线测试接口,通常需要使用工具,比如 postman。
  4. 接口文档太多,不好管理。

这些痛点在前后端分离的大型项目上显得尤为烦躁。而 Swagger2 的出现恰好能个解决这些痛点。因为 Swagger2 有以下功能:

  1. 文档自动更新,只要生成 Api 的网址没变,基本不需要跟前端沟通。
  2. 接口返回结果非常明确,包括数据类型,状态码,错误信息等。
  3. 可以直接在线测试文档,而且还有实例提供给你。
  4. 只需要一次配置便可使用,之后只要会有一份接口文档,非常易于管理。

集成演示

首先新建一个 SpringBoot 项目,还不会的参考我这篇旧文—— 如何使用 IDEA 构建 Spring Boot 工程

构建时,在选择依赖那一步勾选 Web、LomBok、JPA 和 Mysql 依赖。其中 Mysql 可以不勾,因为我这里用于操作实际的数据库,所以我勾选了。

生成 SpringBoot 后的 Pom 文件依赖如下:这里使用的是 2.4.0 的 Swagger2 版本。

<?xml version="1.0" encoding="UTF-8"?>
<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>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>2.1.2.RELEASE</version>
<relativePath/> <!-- lookup parent from repository -->
</parent>
<groupId>com.nasus</groupId>
<artifactId>swagger2</artifactId>
<version>0.0.1-SNAPSHOT</version>
<name>swagger2</name>
<description>Demo project for Swagger2</description> <properties>
<java.version>1.8</java.version>
</properties> <dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency> <dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency> <dependency>
<groupId>mysql</groupId>
<artifactId>mysql-connector-java</artifactId>
<scope>runtime</scope>
</dependency> <dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
</dependency> <dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.4.0</version>
</dependency> <dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.4.0</version>
</dependency>
</dependencies> <build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build> </project>

第二步,在 SpringBoot 启动类(Application)的同级目录新建一个 Swagger 配置类,注意 Swagger2 配置类必须与项目入口类 Application 位于同一级目录,否则生成 Api 文档失败,代码如下:

package com.nasus;

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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2; /**
* Project Name:swagger2-demo <br/>
* Package Name:com.nasus <br/>
* Date:2019/1/22 22:52 <br/>
* <b>Description:</b> TODO: 描述该类的作用 <br/>
*
* @author <a href="turodog@foxmail.com">nasus</a><br/>
* Copyright Notice =========================================================
* This file contains proprietary information of Eastcom Technologies Co. Ltd.
* Copying or reproduction without prior written approval is prohibited.
* Copyright (c) 2019 =======================================================
*/
@Configuration
// 启用 Swagger2
@EnableSwagger2
public class Swagger2 { @Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
// 文档信息对象
.apiInfo(apiInfo())
.select()
// 被注解的包路径
.apis(RequestHandlerSelectors.basePackage("com.nasus.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
// 标题
.title("springboot 利用 swagger 构建 API 文档")
// Api 文档描述
.description("简单优雅的 restful 风格,https://blog.csdn.net/turodog/") .termsOfServiceUrl("https://blog.csdn.net/turodog/")
// 文档作者信息
.contact(new Contact("陈志远", "https://github.com/turoDog", "turodog@foxmail.com"))
// 文档版本
.version("1.0")
.build();
}
}

第三步,配置被注解的 Controller 类,编写各个接口的请求参数,返回结果,接口描述等等,代码如下:

package com.nasus.controller;

import com.nasus.entity.Student;
import com.nasus.service.StudentService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import java.util.List;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.PutMapping;
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 springfox.documentation.annotations.ApiIgnore; /**
* Project Name:swagger2-demo <br/>
* Package Name:com.nasus.controller <br/>
* Date:2019/1/22 22:07 <br/>
* <b>Description:</b> TODO: 描述该类的作用 <br/>
*
* @author <a href="turodog@foxmail.com">nasus</a><br/>
* Copyright Notice =========================================================
* This file contains proprietary information of Eastcom Technologies Co. Ltd.
* Copying or reproduction without prior written approval is prohibited.
* Copyright (c) 2019 =======================================================
*/
@RestController
@RequestMapping("/student")
// @Api:修饰整个类,描述Controller的作用
@Api("StudentController Api 接口文档")
public class StudentController { @Autowired
private StudentService studentService; // @ApiOperation:描述一个类的一个方法,或者说一个接口
@ApiOperation(value="获取所有学生列表", notes="获取所有学生列表")
@RequestMapping(value={""}, method= RequestMethod.GET)
public List<Student> getStudent() {
List<Student> list = studentService.findAll();
return list;
} @ApiOperation(value="添加学生信息", notes="添加学生信息")
// @ApiImplicitParam:一个请求参数
@ApiImplicitParam(name = "student", value = "学生信息详细实体", required = true, dataType = "Student")
@PostMapping("/save")
public Student save(@RequestBody Student student){
return studentService.save(student);
} @ApiOperation(value="获学生信息", notes="根据url的id来获取学生详细信息")
@ApiImplicitParam(name = "id", value = "ID", required = true, dataType = "Integer",paramType = "path")
@GetMapping("/{id}")
public Student findById(@PathVariable("id") Integer id){
return studentService.findById(id);
} @ApiOperation(value="删除学生", notes="根据url的id来指定删除的学生")
@ApiImplicitParam(name = "id", value = "学生ID", required = true, dataType = "Integer",paramType = "path")
@DeleteMapping("/{id}")
public String deleteById(@PathVariable("id") Integer id){
studentService.delete(id);
return "success";
} @ApiOperation(value="更新学生信息", notes="根据url的id来指定更新学生信息")
// @ApiImplicitParams:多个请求参数
@ApiImplicitParams({
@ApiImplicitParam(name = "id", value = "学生ID", required = true, dataType = "Integer",paramType = "path"),
@ApiImplicitParam(name = "student", value = "学生实体student", required = true, dataType = "Student")
})
@PutMapping(value="/{id}")
public String updateStudent(@PathVariable Integer id, @RequestBody Student student) {
Student oldStudent = this.findById(id);
oldStudent.setId(student.getId());
oldStudent.setName(student.getName());
oldStudent.setAge(student.getAge());
studentService.save(oldStudent);
return "success";
} // 使用该注解忽略这个API
@ApiIgnore
@RequestMapping(value = "/hi", method = RequestMethod.GET)
public String jsonTest() {
return " hi you!";
}
}

第四步,启动项目,访问 http://localhost:8080/swagger-ui.html 地址,结果如下图:

项目源代码

github

图解接口

Swagger2 常用注解简介

@ApiOperation:用在方法上,说明方法的作用
1.value: 表示接口名称
2.notes: 表示接口详细描述
@ApiImplicitParams:用在方法上包含一组参数说明
@ApiImplicitParam:用在@ApiImplicitParams注解中,指定一个请求参数的各个方面
1.paramType:参数位置
2.header 对应注解:@RequestHeader
3.query 对应注解:@RequestParam
4.path 对应注解: @PathVariable
5.body 对应注解: @RequestBody
6.name:参数名
7.dataType:参数类型
8.required:参数是否必须传
9.value:参数的描述
10.defaultValue:参数的默认值
@ApiResponses:用于表示一组响应
@ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息
1.code:状态码
2.message:返回自定义信息
3.response:抛出异常的类
@ApiIgnore: 表示该接口函数不对swagger2开放展示
@Api:修饰整个类,描述Controller的作用
@ApiParam:单个参数描述
@ApiModel:用对象来接收参数
@ApiProperty:用对象接收参数时,描述对象的一个字段
@ApiIgnore:使用该注解忽略这个API
@ApiError :发生错误返回的信息

注意事项

@ApiImplicitParam 注解下的 paramType 属性,会影响接口的测试,如果设置的属性跟spring 的注解对应不上,会获取不到参数,例如 paramType=path ,函数内却使用@RequestParam 注解,这样,可能会获取不到传递进来的参数,需要按照上面进行对应,将 @RequestParam 注解改为 @PathVariable 才能获取到对应的参数。

后语

如果看到这里,说明你喜欢这篇文章,请转发、点赞。微信搜索「一个优秀的废人」,关注后回复「1024」送你一套完整的 java 教程。

Spring Boot2 系列教程 (四) | 集成 Swagger2 构建强大的 RESTful API 文档的更多相关文章

  1. 集成 Swagger2 构建强大的 RESTful API 文档

    微信公众号:一个优秀的废人如有问题或建议,请后台留言,我会尽力解决你的问题. 前言 快过年了,不知道你们啥时候放年假,忙不忙.反正我是挺闲的,所以有时间写 blog.今天给你们带来 SpringBoo ...

  2. SpringBoot_06_使用Swagger2构建强大的RESTful API文档

    二.参考资料 1.Spring Boot中使用Swagger2构建强大的RESTful API文档 2.

  3. Spring Boot教程(二十二)使用Swagger2构建强大的RESTful API文档(1)

    由于Spring Boot能够快速开发.便捷部署等特性,相信有很大一部分Spring Boot的用户会用来构建RESTful API.而我们构建RESTful API的目的通常都是由于多终端的原因,这 ...

  4. Spring Boot中使用Swagger2构建强大的RESTful API文档

    由于Spring Boot能够快速开发.便捷部署等特性,相信有很大一部分Spring Boot的用户会用来构建RESTful API.而我们构建RESTful API的目的通常都是由于多终端的原因,这 ...

  5. Spring Boot 中使用 Swagger2 构建强大的 RESTful API 文档

    项目现状:由于前后端分离,没有很好的前后端合作工具. 由于接口众多,并且细节复杂(需要考虑不同的HTTP请求类型.HTTP头部信息.HTTP请求内容等),高质量地创建这份文档本身就是件非常吃力的事,下 ...

  6. 使用Swagger2构建强大的RESTful API文档(1)(二十二)

    由于Spring Boot能够快速开发.便捷部署等特性,相信有很大一部分Spring Boot的用户会用来构建RESTful API.而我们构建RESTful API的目的通常都是由于多终端的原因,这 ...

  7. Spring Boot教程(二十三)使用Swagger2构建强大的RESTful API文档(2)

    添加文档内容 在完成了上述配置后,其实已经可以生产文档内容,但是这样的文档主要针对请求本身,而描述主要来源于函数等命名产生,对用户并不友好,我们通常需要自己增加一些说明来丰富文档内容.如下所示,我们通 ...

  8. 使用Swagger2构建强大的RESTful API文档(2)(二十三)

    添加文档内容 在完成了上述配置后,其实已经可以生产文档内容,但是这样的文档主要针对请求本身,而描述主要来源于函数等命名产生,对用户并不友好,我们通常需要自己增加一些说明来丰富文档内容.如下所示,我们通 ...

  9. SpringBoot使用Swagger2搭建强大的RESTful API 文档功能

    swagger用于定义API文档. Swagger2的使用 Maven Plugin添加Swagger2相关jar包 <!--swagger2 start--> <dependenc ...

随机推荐

  1. js将单个反斜杠转化为斜杠的问题

    var two="https://192.255.255.255:3215/2019/2/26/16/13/b2e8929483c66cefddbe1e49a007e3f8-47358FC3 ...

  2. react入门:todo应用

    <!DOCTYPE html> <html lang="en"> <head> <meta charset="UTF-8&quo ...

  3. springmvc单Redis实例实现分布式锁(解决锁超时问题)

    一.前言 关于redis分布式锁, 查了很多资料, 发现很多只是实现了最基础的功能, 但是, 并没有解决当锁已超时而业务逻辑还未执行完的问题, 这样会导致: A线程超时时间设为10s(为了解决死锁问题 ...

  4. Python--day60--建立第一个Djiango项目

  5. electron-vue 窗口拖拽及自定义边框,及关闭缩小放大化方法

    1.窗口的最小化按钮和关闭按钮以及标题栏自定义,不使用 electron 自身携带的原生标题栏 在src文件夹下main下index.js文件添加 mainWindow = new BrowserWi ...

  6. 12563 - Jin Ge Jin Qu hao——[DP递推]

    (If you smiled when you see the title, this problem is for you ^_^) For those who don’t know KTV, se ...

  7. QuartusII 13.0的完美破解

    网络上破解QuartusII 13.0软件的方法都不行,最后经过本人总结测试(独创),最终实现了QuartusII 13.0的破解,破解方法如下: 网上常规操作之后,会得到一个“license.dat ...

  8. dynamic web module version

    Ser vlet 3十二月2009开发平台标准版6,6可插性,易于开发,异步ser vlet,安全,文件上传 Ser vlet 2.5九月2005开发平台标准版5,5需要平台标准版5,支持注释 Ser ...

  9. Delta Lake源码分析

    目录 Delta Lake源码分析 Delta Lake元数据 snapshot生成 日志提交 冲突检测(并发控制) delete update merge Delta Lake源码分析 Delta ...

  10. 【15.93%】【codeforces 672D】Robin Hood

    time limit per test1 second memory limit per test256 megabytes inputstandard input outputstandard ou ...