SpringBoot整合Swagger和Actuator

迷南。 2022-01-14 08:07 398阅读 0赞

## 前言 ##

本篇文章主要介绍的是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使用教程][Postman]

### Swagger 相关地址 ###

*  Swagger官网：[http://swagger.io][http_swagger.io]
 *  Swagger的GitHub地址：[https://github.com/swagger-api][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>
    	
    		
    	<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][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的界面了。

界面的示例图如下:

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly94dXd1amluZy5ibG9nLmNzZG4ubmV0_size_16_color_FFFFFF_t_70]

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

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

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly94dXd1amluZy5ibG9nLmNzZG4ubmV0_size_16_color_FFFFFF_t_70 1]

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

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

### 功能测试 ###

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

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

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

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

> [http://localhost:8888/monitor/health][http_localhost_8888_monitor_health]

即可查看。

**示例图:**  
![在这里插入图片描述][20190615162314189.png]

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

在浏览器输入:

> [http://localhost:8888/monitor/info][http_localhost_8888_monitor_info]

**示例图:**  
![在这里插入图片描述][20190615162335237.png]

## 其它 ##

### 项目地址 ###

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

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

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

### SpringBoot整合系列的文章 ###

[SpringBoot系列博客:][SpringBoot]

*  [SpringBoot的Restful风格的服务][SpringBoot_Restful]
 *  [SpringBoot配置文件的读取以及过滤器和拦截器的使用][SpringBoot 1]
 *  [SpringBoot+Mybatis+ Druid+PageHelper实现多数据源并分页][SpringBoot_Mybatis_ Druid_PageHelper]
 *  [SpringBoot整合ElasticSearch实现多版本的兼容][SpringBoot_ElasticSearch]
 *  [SpringBoot整合Kafka和Storm][SpringBoot_Kafka_Storm]
 *  [SpringBoot整合Jsp和Thymeleaf][SpringBoot_Jsp_Thymeleaf]
 *  [SpringBoot整合Netty并使用Protobuf进行数据传输][SpringBoot_Netty_Protobuf]
 *  [SpringBoot简单打包部署][SpringBoot 2]
 *  [SpringBoot整合Redis使用Restful风格实现CRUD功能][SpringBoot_Redis_Restful_CRUD]
 *  [SpringBoot优雅的全局异常处理][SpringBoot 3]
 *  [SpringBoot项目实现文件上传和邮件发送][SpringBoot 4]

### 音乐推荐 ###

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

[Postman]: https://blog.csdn.net/qazwsxpcm/article/details/70578600
[http_swagger.io]: http://swagger.io
[https_github.com_swagger-api]: https://github.com/swagger-api
[https_github.com_swagger-api_swagger-core_wiki_Swagger-2.X---Annotations]: https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Annotations
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly94dXd1amluZy5ibG9nLmNzZG4ubmV0_size_16_color_FFFFFF_t_70]: /images/20220114/bc3d57993ac446ceae4529ca862a4515.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly94dXd1amluZy5ibG9nLmNzZG4ubmV0_size_16_color_FFFFFF_t_70 1]: /images/20220114/0ba3277bda6446c9b380a2f27cf780d4.png
[https_www.baeldung.com_spring-boot-actuators]: https://www.baeldung.com/spring-boot-actuators
[SpringCloud_----- _Hystrix_Dashboard]: https://www.cnblogs.com/xuwujing/p/10446126.html
[20190615162306522.png]: /images/20220114/38e264d3b1c34435a25b883bdb14b2f5.png
[http_localhost_8888_monitor_health]: http://localhost:8888/monitor/health
[20190615162314189.png]: /images/20220114/863d93af1c3a423aad984ba1cfd70c76.png
[http_localhost_8888_monitor_info]: http://localhost:8888/monitor/info
[20190615162335237.png]: /images/20220114/71e6743f18e04704ac96a57671e3306c.png
[https_github.com_xuwujing_springBoot-study_tree_master_springboot-swagger]: https://github.com/xuwujing/springBoot-study/tree/master/springboot-swagger
[https_github.com_xuwujing_springBoot-study_tree_master_springboot-actuator]: https://github.com/xuwujing/springBoot-study/tree/master/springboot-actuator
[https_github.com_xuwujing_springBoot-study]: https://github.com/xuwujing/springBoot-study
[SpringBoot]: https://www.cnblogs.com/xuwujing/category/1145997.html
[SpringBoot_Restful]: https://www.cnblogs.com/xuwujing/p/8260935.html
[SpringBoot 1]: https://www.cnblogs.com/xuwujing/p/8485832.html
[SpringBoot_Mybatis_ Druid_PageHelper]: https://www.cnblogs.com/xuwujing/p/8964927.html
[SpringBoot_ElasticSearch]: https://www.cnblogs.com/xuwujing/p/8998168.html
[SpringBoot_Kafka_Storm]: https://www.cnblogs.com/xuwujing/p/9021561.html
[SpringBoot_Jsp_Thymeleaf]: https://www.cnblogs.com/xuwujing/p/9297165.html
[SpringBoot_Netty_Protobuf]: https://www.cnblogs.com/xuwujing/p/9321395.html
[SpringBoot 2]: https://www.cnblogs.com/xuwujing/p/9471802.html
[SpringBoot_Redis_Restful_CRUD]: https://www.cnblogs.com/xuwujing/p/10835571.html
[SpringBoot 3]: https://www.cnblogs.com/xuwujing/p/10933082.html
[SpringBoot 4]: https://www.cnblogs.com/xuwujing/p/10945698.html
[http_www.cnblogs.com_xuwujing]: http://www.cnblogs.com/xuwujing
[http_blog.csdn.net_qazwsxpcm]: http://blog.csdn.net/qazwsxpcm
[http_www.panchengming.com]: http://www.panchengming.com