SpringBoot整合Swagger和Actuator

时间 2020-05-22

标签 springboot 整合 swagger actuator 栏目 Spring 繁體版

原文原文链接

前言

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

SpringBoot整合Swagger

说明：若是想直接获取工程那么能够直接跳到底部，经过连接下载工程代码。java

Swagger 介绍

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

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使用教程github

Swagger 相关地址

Swagger官网：http://swagger.io
Swagger的GitHub地址：https://github.com/swagger-api

开发准备

环境要求web

JDK：1.8spring

SpringBoot：1.5.9.RELEASE数据库

首先仍是Maven的相关依赖:api

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文件以下:

<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) 这篇文章。