腳本之家服務器常用軟件

快捷導航

SpringBoot整合Swagger和Actuator的使用教程詳解

更新時間：2019年06月18日 09:40:07 作者：虛無境

Swagger 是一套基于 OpenAPI 規(guī)范構建的開源工具，可以幫助我們設計、構建、記錄以及使用 Rest API。本篇文章主要介紹的是SpringBoot整合Swagger(API文檔生成框架)和SpringBoot整合Actuator(項目監(jiān)控)使用教程。感興趣的朋友一起看看吧

前言

本篇文章主要介紹的是SpringBoot整合Swagger(API文檔生成框架)和SpringBoot整合Actuator(項目監(jiān)控)使用教程。

SpringBoot整合Swagger

說明：如果想直接獲取工程那么可以直接跳到底部，通過鏈接下載工程代碼。

Swagger 介紹

Swagger 是一套基于 OpenAPI 規(guī)范構建的開源工具，可以幫助我們設計、構建、記錄以及使用 Rest API。Swagger 主要包含了以下三個部分：

Swagger Editor：基于瀏覽器的編輯器，我們可以使用它編寫我們 OpenAPI 規(guī)范。
Swagger UI：它會將我們編寫的 OpenAPI 規(guī)范呈現(xiàn)為交互式的 API 文檔，后文我將使用瀏覽器來查看并且操作我們的 Rest API。
Swagger Codegen：它可以通過為 OpenAPI（以前稱為 Swagger）規(guī)范定義的任何 API 生成服務器存根和客戶端 SDK 來簡化構建過程。

Swagger優(yōu)缺點

優(yōu)點

易用性好，Swagger UI提供很好的API接口的UI界面，可以很方面的進行API接口的調用。
時效性和可維護性好，API文檔隨著代碼變更而變更。 Swagger是根據(jù)注解來生成文API檔的，我們可以在變更代碼的時候順便更改相應的注解即可。
易于測試，可以將文檔規(guī)范導入相關的工具（例如 SoapUI）, 這些工具將會為我們自動地創(chuàng)建自動化測試。

缺點

重復利用性差，因為Swagger畢竟是網(wǎng)頁打開，在進行接口測試的時候很多參數(shù)無法進行保存，因此不易于重復利用。復雜的場景不易模擬，比如使用token鑒權的，可能每次都需要先模擬登錄，再來進行接口調用。
不過上述的這些缺點其實也無傷大雅，可以配合Postman來一起使用！
Postman可以保存參數(shù)并持久化生成文件，也可以在Header中保存Token信息，也可以動態(tài)的生成數(shù)字簽名等等。

如果有興趣的話，可以看看我之前寫的這篇文章。

地址: Postman使用教程

Swagger 相關地址

Swagger官網(wǎng)：http://swagger.ioSwagger的

GitHub地址：https://github.com/swagger-api

開發(fā)準備

環(huán)境要求

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已經(jīng)整合好的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注解來給參數(shù)增加說明，其中 value 是標題,notes是詳細說明。

下列是Swagger的一些注解說明，更詳細的可以查看官方的wiki文檔。

@Api：將類標記為Swagger資源。

@ApiImplicitParam：表示API操作中的單個參數(shù)。

@ApiImplicitParams：一個包裝器，允許列出多個ApiImplicitParam對象。

@ApiModel：提供有關Swagger模型的其他信息，比如描述POJO對象。

@ApiModelProperty：添加和操作模型屬性的數(shù)據(jù)。

@ApiOperation：描述針對特定路徑的操作或通常是HTTP方法。

@ApiParam：為操作參數(shù)添加其他元數(shù)據(jù)。

@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="創(chuàng)建用戶", notes="根據(jù)User對象創(chuàng)建用戶")
 @ApiImplicitParam(name = "user", value = "用戶詳細實體user", required = true, dataType = "User")
 @PostMapping("/user")
 public boolean insert(@RequestBody User user) {
  logger.info("開始新增用戶信息！請求參數(shù):{}",user);
  return true;
 }
 @ApiOperation(value="更新用戶", notes="根據(jù)User對象更新用戶")
 @ApiImplicitParam(name = "user", value = "用戶詳細實體user", required = true, dataType = "User")
 @PutMapping("/user")
 public boolean update(@RequestBody User user) {
  logger.info("開始更新用戶信息！請求參數(shù):{}",user);
  return true;
 }
 @ApiOperation(value="刪除用戶", notes="根據(jù)User對象刪除用戶")
 @ApiImplicitParam(name = "user", value = "用戶詳細實體user", required = true, dataType = "User")
 @DeleteMapping("/user")
 public boolean delete(@RequestBody User user) {
  logger.info("開始刪除用戶信息！請求參數(shù):{}",user);
  return true;
 }
 @ApiOperation(value="獲取用戶列表", notes="根據(jù)User對象查詢用戶信息")
 @ApiImplicitParam(name = "user", value = "用戶詳細實體user", required = true, dataType = "User")
 @GetMapping("/user")
 public User findByUser(User user) {
  logger.info("開始查詢用戶列表，請求參數(shù):{}",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為我們的應用程序帶來了生產(chǎn)就緒功能。通過這種依賴關系監(jiān)控我們的應用程序，收集指標，了解流量或數(shù)據(jù)庫的狀態(tài)變得微不足道。這個庫的主要好處是我們可以獲得生產(chǎn)級工具，而無需自己實際實現(xiàn)這些功能。Actuator主要用于公開有關正在運行的應用程序的運行信息 - 運行狀況，指標，信息，轉儲，env等。它使用HTTP端點或JMX bean來使我們能夠與它進行交互。一旦這個依賴關系在類路徑上，就可以開箱即用幾個端點。與大多數(shù)Spring模塊一樣，我們可以通過多種方式輕松配置或擴展它。

注意事項

Actuator的1.x版本和2.x版本差別很大，本文介紹的是1.x版本。

Actuator現(xiàn)在與技術無關，而在1.x中，它與MVC相關聯(lián)，因此與Servlet API相關聯(lián)。
在2.x中，Actuator定義了它的模型，可插拔和可擴展，而不依賴于MVC。因此，通過這個新模型，我們可以利用MVC和WebFlux作為底層Web技術。
此外，可以通過實施正確的適配器來添加即將到來的技術。
最后，JMX仍然支持在沒有任何其他代碼的情況下公開端點。

上述的說明參考Actuator官網(wǎng)。

官網(wǎng)地址:

https://www.baeldung.com/spring-boot-actuators

開發(fā)準備

環(huán)境要求

JDK：1.8

SpringBoot：1.5.9.RELEASE

首先還是Maven的相關依賴:

pom.xml文件如下:

 @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程序啟動成功!");
 }
 }

然后就是application.yml的文件配置，這里的配置主要是指定監(jiān)控的端口和路徑以及關閉安全認證等等。

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

代碼編寫

其實這塊不需要代碼的編寫，因為它只需要你在項目中添加了該依賴并進行配置之后即可使用。這里我們在創(chuàng)建一個普通的SpringBoot項目并且添加了Actuator的相關依賴，然后通過調用Actuator提供的一些接口就可以得知相關的信息。
這些接口的一些說明如下:

1./autoconfig 可以得到配置生效信息

/configprops 可以得到屬性的內容和默認值/beans 可以得到bean的別名、類型、是否單例、類的地址、依賴等信息/dump 可以得到線程名、線程ID、線程的狀態(tài)、是否等待鎖資源等信息/env 可以得到環(huán)境變量、JVM 屬性、命令行參數(shù)、項目使用的jar包等信息
5.1 /sun.boot.library.path 可以得到JDK安裝路徑/health 可以得到磁盤檢測和數(shù)據(jù)庫檢測等信息/mappings 可以得到全部的URI路徑，以及它們和控制器的映射關系/metrics 可以得到JVM內容使用、GC情況、類加載信息
8.1 /gc.* 可以得到GC相關信息
8.2 /mem.* 可以得到內存信息 .../info 可以得到自定義的配置信息/shutdown 可以進行關閉程序 post請求/trace 可以得到所Web請求的詳細信息
12 ....

更多的相關配置說明可以查看官方文檔！

如果通過通過接口信息返回的數(shù)據(jù)進行查看不夠清晰明了的話，可以結合SpringCloud Hystrix-Dashboard進行轉換圖表查看。

具體使用可以參考： SpringCloud學習系列之三----- 斷路器(Hystrix)和斷路器監(jiān)控(Dashboard) 這篇文章。

功能測試

我們成功啟動該程序之后，便來進行測試。

首先查看啟動日志，會發(fā)現(xiàn)啟動了兩個端口，一個是springboot項目自身的端口，還有一個Actuator監(jiān)控的端口。

示例圖：