SpringBoot整合Swagger和Actuator

前言

本篇文章主要介绍的是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 相关地址

开发准备

环境要求

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代码配置如下:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
@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层相关的代码编写。这里我们首先编写一个实体类。

实体类

又是万能的用户表

1
2
3
4
5
6
7
8
9
10
11
12
13
14
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

控制层代码如下:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
@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项目基本一样。

代码如下:

1
2
3
4
5
6
7
8
9
10
11
@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文件如下:

  <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-actuator</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>
</dependencies>

然后就是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 可以得到配置生效信息

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

更多的相关配置说明可以查看官方文档!
如果通过通过接口信息返回的数据进行查看不够清晰明了的话,可以结合SpringCloud Hystrix-Dashboard进行转换图表查看。
具体使用可以参考: SpringCloud学习系列之三—– 断路器(Hystrix)和断路器监控(Dashboard) 这篇文章。

功能测试

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

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

示例图:
在这里插入图片描述
对外提供的Actuator主要是可以帮助我们获取一些程序以及一些环境的相关信息。

比如获取程序健康状态。
在浏览器输入:

http://localhost:8888/monitor/health

即可查看。

示例图:
在这里插入图片描述

当然也可以自定一些程序信息,比如定义程序版本。

在浏览器输入:

http://localhost:8888/monitor/info

示例图:
在这里插入图片描述

其它

项目地址

SpringBoot整合Swagger的项目工程地址:
https://github.com/xuwujing/springBoot-study/tree/master/springboot-swagger

SpringBoot整合Actuator的项目工程地址:
https://github.com/xuwujing/springBoot-study/tree/master/springboot-actuator

SpringBoot整个集合的地址:
https://github.com/xuwujing/springBoot-study

SpringBoot整合系列的文章

SpringBoot系列博客:

音乐推荐

原创不易,如果感觉不错,希望给个推荐!您的支持是我写作的最大动力!
版权声明:
作者:虚无境
博客园出处:http://www.cnblogs.com/xuwujing
CSDN出处:http://blog.csdn.net/qazwsxpcm    
个人博客出处:http://www.panchengming.com

+
------ 本文结束 ------