SpringBoot整合Swagger和Actuator的使用教程详解

2021-04-03 我要评论

前言

本篇文章主要介绍的是SpringBoot整合Swagger(API文档生成框架)和SpringBoot整合Actuator(项目监控)使用教程。

SpringBoot整合Swagger

说明：如果想直接获取工程那么可以直接跳到底部，通过链接下载工程代码。

Swagger 介绍

Swagger 是一套基于 OpenAPI 规范构建的开源工具，可以帮助我们设计、构建、记录以及使用 Rest API。Swagger 主要包含了以下三个部分：

Swagger Editor：基于浏览器的编辑器，我们可以使用它编写我们 OpenAPI 规范。
Swagger UI：它会将我们编写的 OpenAPI 规范呈现为交互式的 API 文档，后文我将使用浏览器来查看并且操作我们的 Rest API。
Swagger Codegen：它可以通过为 OpenAPI（以前称为 Swagger）规范定义的任何 API 生成服务器存根和客户端 SDK 来简化构建过程。

Swagger优缺点

优点

易用性好，Swagger UI提供很好的API接口的UI界面，可以很方面的进行API接口的调用。
时效性和可维护性好，API文档随着代码变更而变更。 Swagger是根据注解来生成文API档的，我们可以在变更代码的时候顺便更改相应的注解即可。
易于测试，可以将文档规范导入相关的工具（例如 SoapUI）, 这些工具将会为我们自动地创建自动化测试。

缺点

重复利用性差，因为Swagger毕竟是网页打开，在进行接口测试的时候很多参数无法进行保存，因此不易于重复利用。复杂的场景不易模拟，比如使用token鉴权的，可能每次都需要先模拟登录，再来进行接口调用。
不过上述的这些缺点其实也无伤大雅，可以配合Postman来一起使用！
Postman可以保存参数并持久化生成文件，也可以在Header中保存Token信息，也可以动态的生成数字签名等等。

如果有兴趣的话，可以看看我之前写的这篇文章。

地址: Postman使用教程

Swagger 相关地址

Swagger官网：http://swagger.ioSwagger的

GitHub地址：https://github.com/swagger-api

开发准备

环境要求

JDK：1.8

SpringBoot：1.5.9.RELEASE

首先还是Maven的相关依赖:

pom.xml文件如下:

 <properties>
 <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
 <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
 <java.version>1.8</java.version>
 <maven.compiler.source>1.8</maven.compiler.source>
 <maven.compiler.target>1.8</maven.compiler.target>
</properties>
<parent>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-starter-parent</artifactId>
 <version>1.5.9.RELEASE</version>
 <relativePath/>
</parent>
<dependencies>
 <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>
 <dependency>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-devtools</artifactId>
 <optional>true</optional>
 <scope>test</scope>
 </dependency>
 <!-- swagger RESTful API -->
 <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>

注: Swagger的jar包既可原生的 Swagger的架包，也可以选择maven仓库SpringBoot已经整合好的Swagger的架包。

application.properties的文件的配置和一般的SpringBoot项目一样即可。

代码编写

SpringBoot使用Swagger其实很简单，只需要在启动的时候添加@EnableSwagger2注解开启，然后再使用@Bean注解初始化一些相应的配置即可，比如编辑Swagger UI界面的信息，指定Swagger负责扫描的package等等。

Swagger代码配置如下:

@Configuration
 @EnableSwagger2
 public class Swagger2 {
 @Bean
 public Docket createRestApi() {
  return new Docket(DocumentationType.SWAGGER_2)
   .apiInfo(apiInfo())
   .select()
   .apis(RequestHandlerSelectors.basePackage("com.pancm"))
   .paths(PathSelectors.any())
   .build();
 }
 private ApiInfo apiInfo() {
  return new ApiInfoBuilder()
   .title("Spring Boot中使用Swagger2构建RESTful APIs")
   .description("测试")
   .termsOfServiceUrl("http://www.panchengming.com/")
   .contact("xuwujing")
   .version("1.0")
   .build();
 }
 }

因为Swagger主要是用于生成API文档，因此这里我们可以直接编写控制层的相关代码，忽略掉Service层和Dao层相关的代码编写。这里我们首先编写一个实体类。

实体类

又是万能的用户表

public class User { 
  private Long id; 
  private String name;
  private Integer age; 
 //getter 和 setter 略
 
 }

Controller 控制层

Swagger主要的使用就是在控制层这块，它是通过一些注解来为接口提供API文档。下述的代码中主要使用的注解为这两个@ApiOperation和 @ApiImplicitParam这两个，@ApiOperation注解来给API增加说明并通过@ApiImplicitParams注解来给参数增加说明，其中 value 是标题,notes是详细说明。

下列是Swagger的一些注解说明，更详细的可以查看官方的wiki文档。

@Api：将类标记为Swagger资源。

@ApiImplicitParam：表示API操作中的单个参数。

@ApiImplicitParams：一个包装器，允许列出多个ApiImplicitParam对象。

@ApiModel：提供有关Swagger模型的其他信息，比如描述POJO对象。

@ApiModelProperty：添加和操作模型属性的数据。

@ApiOperation：描述针对特定路径的操作或通常是HTTP方法。

@ApiParam：为操作参数添加其他元数据。

@ApiResponse：描述操作的可能响应。

@ApiResponses：一个包装器，允许列出多个ApiResponse对象。

@Authorization：声明要在资源或操作上使用的授权方案。

@AuthorizationScope：描述OAuth2授权范围。

@ResponseHeader：表示可以作为响应的一部分提供的标头。

@ApiProperty：描述POJO对象中的属性值。@ApiError ：接口错误所返回的信息...

官方wiki文档地址:

https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Annotations

控制层代码如下:

@RestController
 @RequestMapping(value = "/api")
 public class UserRestController {
 private final Logger logger = LoggerFactory.getLogger(this.getClass());
 @ApiOperation(value="创建用户", notes="根据User对象创建用户")
 @ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
 @PostMapping("/user")
 public boolean insert(@RequestBody User user) {
  logger.info("开始新增用户信息！请求参数:{}",user);
  return true;
 }
 @ApiOperation(value="更新用户", notes="根据User对象更新用户")
 @ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
 @PutMapping("/user")
 public boolean update(@RequestBody User user) {
  logger.info("开始更新用户信息！请求参数:{}",user);
  return true;
 }
 @ApiOperation(value="删除用户", notes="根据User对象删除用户")
 @ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
 @DeleteMapping("/user")
 public boolean delete(@RequestBody User user) {
  logger.info("开始删除用户信息！请求参数:{}",user);
  return true;
 }
 @ApiOperation(value="获取用户列表", notes="根据User对象查询用户信息")
 @ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
 @GetMapping("/user")
 public User findByUser(User user) {
  logger.info("开始查询用户列表，请求参数:{}",user);
  User user2 =new User();
  user2.setId(1L);
  user2.setAge(18);
  user2.setName("xuwujing");
  return user2;
 }
 }

App 入口

和普通的SpringBoot项目基本一样。

代码如下:

 @SpringBootApplication
 public class SwaggerApplication {
 private static final Logger logger = LoggerFactory.getLogger(SwaggerApplication.class);
 public static void main(String[] args) {
  SpringApplication.run(SwaggerApplication.class, args);
  logger.info("Swagger程序启动成功!");
 }
 }

功能测试

我们成功启动该程序之后，在浏览器上输入:http://localhost:8183/swagger-ui.html, 就可以看到Swagger的界面了。

界面的示例图如下:

由于Swagger的操作主要是在界面操作，因此用图片会更加有说服力。

使用GET请求测试示例图如下:

SpringBoot整合Actuator

说明：如果想直接获取工程那么可以直接跳到底部，通过链接下载工程代码。

Actuator介绍

从本质上讲，Actuator为我们的应用程序带来了生产就绪功能。通过这种依赖关系监控我们的应用程序，收集指标，了解流量或数据库的状态变得微不足道。这个库的主要好处是我们可以获得生产级工具，而无需自己实际实现这些功能。Actuator主要用于公开有关正在运行的应用程序的运行信息 - 运行状况，指标，信息，转储，env等。它使用HTTP端点或JMX bean来使我们能够与它进行交互。一旦这个依赖关系在类路径上，就可以开箱即用几个端点。与大多数Spring模块一样，我们可以通过多种方式轻松配置或扩展它。

注意事项

Actuator的1.x版本和2.x版本差别很大，本文介绍的是1.x版本。

Actuator现在与技术无关，而在1.x中，它与MVC相关联，因此与Servlet API相关联。
在2.x中，Actuator定义了它的模型，可插拔和可扩展，而不依赖于MVC。因此，通过这个新模型，我们可以利用MVC和WebFlux作为底层Web技术。
此外，可以通过实施正确的适配器来添加即将到来的技术。
最后，JMX仍然支持在没有任何其他代码的情况下公开端点。

上述的说明参考Actuator官网。

官网地址:

https://www.baeldung.com/spring-boot-actuators

开发准备

环境要求

JDK：1.8

SpringBoot：1.5.9.RELEASE

首先还是Maven的相关依赖:

pom.xml文件如下:

 @SpringBootApplication
 public class SwaggerApplication {
 private static final Logger logger = LoggerFactory.getLogger(SwaggerApplication.class);
 public static void main(String[] args) {
  SpringApplication.run(SwaggerApplication.class, args);
  logger.info("Swagger程序启动成功!");
 }
 }

然后就是application.yml的文件配置，这里的配置主要是指定监控的端口和路径以及关闭安全认证等等。

application.yml:

server:
 port: 8181 
management:
 security:
 enabled: false 
 port: 8888 
 context-path: /monitor
 
endpoints:
 shutdown:
 enabled: true
 
info:
 app:
 name:springboot-actuator
 version:1.0

代码编写

其实这块不需要代码的编写，因为它只需要你在项目中添加了该依赖并进行配置之后即可使用。这里我们在创建一个普通的SpringBoot项目并且添加了Actuator的相关依赖，然后通过调用Actuator提供的一些接口就可以得知相关的信息。
这些接口的一些说明如下:

1./autoconfig 可以得到配置生效信息

/configprops 可以得到属性的内容和默认值/beans 可以得到bean的别名、类型、是否单例、类的地址、依赖等信息/dump 可以得到线程名、线程ID、线程的状态、是否等待锁资源等信息/env 可以得到环境变量、JVM 属性、命令行参数、项目使用的jar包等信息
5.1 /sun.boot.library.path 可以得到JDK安装路径/health 可以得到磁盘检测和数据库检测等信息/mappings 可以得到全部的URI路径，以及它们和控制器的映射关系/metrics 可以得到JVM内容使用、GC情况、类加载信息
8.1 /gc.* 可以得到GC相关信息
8.2 /mem.* 可以得到内存信息 .../info 可以得到自定义的配置信息/shutdown 可以进行关闭程序 post请求/trace 可以得到所Web请求的详细信息
12 ....

更多的相关配置说明可以查看官方文档！

如果通过通过接口信息返回的数据进行查看不够清晰明了的话，可以结合SpringCloud Hystrix-Dashboard进行转换图表查看。

具体使用可以参考： SpringCloud学习系列之三----- 断路器(Hystrix)和断路器监控(Dashboard) 这篇文章。

功能测试

我们成功启动该程序之后，便来进行测试。

首先查看启动日志，会发现启动了两个端口，一个是springboot项目自身的端口，还有一个Actuator监控的端口。

示例图：