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为咱们的应用程序带来了生产就绪功能。经过这种依赖关系监控咱们的应用程序，收集指标，了解流量或数据库的状态变得微不足道。这个库的主要好处是咱们能够得到生产级工具，而无需本身实际实现这些功能。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系列博客:

• 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