本篇文章主要介绍的是SpringBoot整合Swagger(API文档生成框架)和SpringBoot整合Actuator(项目监控)使用教程。
Swagger 是一套基于 OpenAPI 规范构建的开源工具,可以帮助我们设计、构建、记录以及使用 Rest API。Swagger 主要包含了以下三个部分:
不过上述的这些缺点其实也无伤大雅,可以配合 Postman 来一起使用!
Postman可以保存参数并持久化生成文件,也可以在Header中保存Token信息,也可以动态的生成数字签名等等。
如果有兴趣的话,可以看看我之前写的这篇文章。
地址: Postman使用教程
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等等。
@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 略 }
Swagger主要的使用就是在控制层这块,它是通过一些注解来为接口提供API文档。下述的代码中主要使用的注解为这两个 @ApiOperation
和 @ApiImplicitParam
这两个, @ApiOperation
注解来给API增加说明并通过 @ApiImplicitParams
注解来给参数增加说明,其中 value
是标题, notes
是详细说明。
下列是Swagger的一些注解说明,更详细的可以查看官方的wiki文档。
官方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; } }
和普通的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请求测试示例图如下:
从本质上讲,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-actuatorsSpringBoot: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的文件配置,这里的配置主要是指定监控的端口和路径以及关闭安全认证等等。
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 可以得到配置生效信息
可以得到GC相关信息
8.2 /mem.
可以得到内存信息 …更多的相关配置说明可以查看官方文档!
如果通过通过接口信息返回的数据进行查看不够清晰明了的话,可以结合SpringCloud Hystrix-Dashboard进行转换图表查看。
具体使用可以参考: SpringCloud学习系列之三—– 断路器(Hystrix)和断路器监控(Dashboard) 这篇文章。
我们成功启动该程序之后,便来进行测试。
首先查看启动日志,会发现启动了两个端口,一个是springboot项目自身的端口,还有一个Actuator监控的端口。
示例图:
对外提供的Actuator主要是可以帮助我们获取一些程序以及一些环境的相关信息。
比如获取程序健康状态。
在浏览器输入:
http://localhost:8888/monitor/health
即可查看。
示例图:
当然也可以自定一些程序信息,比如定义程序版本。
在浏览器输入:
http://localhost:8888/monitor/info
示例图: