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 相关地址

• Swagger官网：http://swagger.io
• Swagger的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的1.x版本和2.x版本差别很大，本文介绍的是1.x版本。

上述的说明参考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提供的一些接口就可以得知相关的信息。

这些接口的一些说明如下:

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

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

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

功能测试

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

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

示例图：

对外提供的Actuator主要是可以帮助我们获取一些程序以及一些环境的相关信息。

比如获取程序健康状态。

在浏览器输入:

即可查看。

示例图:

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

在浏览器输入:

示例图:

其它

项目地址

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系列博客:

• SpringBoot的Restful风格的服务

• SpringBoot配置文件的读取以及过滤器和拦截器的使用

• SpringBoot+Mybatis+ Druid+PageHelper实现多数据源并分页

• SpringBoot整合ElasticSearch实现多版本的兼容

• SpringBoot整合Kafka和Storm

• SpringBoot整合Jsp和Thymeleaf

• SpringBoot整合Netty并使用Protobuf进行数据传输

• SpringBoot简单打包部署

• SpringBoot整合Redis使用Restful风格实现CRUD功能

• SpringBoot优雅的全局异常处理

• SpringBoot项目实现文件上传和邮件发送

音乐推荐

原创不易，如果感觉不错，希望给个推荐！您的支持是我写作的最大动力！

版权声明:

作者：虚无境

博客园出处：http://www.cnblogs.com/xuwujing

CSDN出处：http://blog.csdn.net/qazwsxpcm　　　　

个人博客出处：http://www.panchengming.com