前言
本篇文章主要介绍的是 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.YAML 的文件配置, 这里的配置主要是指定监控的端口和路径以及关闭安全认证等等.
- application.YAML:
- 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 可以得到配置生效信息
/configprops 可以得到属性的内容和默认值
/beans 可 以得到 bean 的别名, 类型, 是否单例, 类的地址, 依赖等信息
/dump 可 以得到线程名, 线程 ID, 线程的状态, 是否等待锁资源等信息
/env 可以得到环境变量, JVM 属性, 命令行参数, 项目使用的 jar 包等信息
5.1 /sun.boot.library.path 可以得到 JDK 安装路径
/health 可以得到磁盘检测和数据库检测等信息
/mappings 可以得到全部的 URI 路径, 以及它们和控制器的映射关系
/metrics 可以得到 JVM 内容使用, GC 情况, 类加载信息
8.1 /gc.* 可以得到 GC 相关信息
8.2 /mem.* 可以得到内存信息 ...
/info 可以得到自定义的配置信息
/shutdown 可以进行关闭程序 post 请求
/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 项目实现文件上传和邮件发送
音乐推荐
原创不易, 如果感觉不错, 希望给个推荐! 您的支持是我写作的最大动力!
来源: https://www.cnblogs.com/xuwujing/p/11042674.html