前言

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

SpringBoot整合Swagger

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

Swagger 介紹

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

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

Swagger優(yōu)缺點

優(yōu)點

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

缺點

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

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

地址: Postman使用教程

Swagger 相關(guān)地址

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

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

開發(fā)準備

環(huán)境要求

JDK：1.8

SpringBoot：1.5.9.RELEASE

首先還是Maven的相關(guān)依賴:

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注解初始化一些相應(yīng)的配置即可，比如編輯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構(gòu)建RESTful APIs")
   .description("測試")
   .termsOfServiceUrl("http://www.panchengming.com/")
   .contact("xuwujing")
   .version("1.0")
   .build();
 }
 }

因為Swagger主要是用于生成API文檔，因此這里我們可以直接編寫控制層的相關(guān)代碼，忽略掉Service層和Dao層相關(guān)的代碼編寫。這里我們首先編寫一個實體類。

實體類

又是萬能的用戶表

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：提供有關(guān)Swagger模型的其他信息，比如描述POJO對象。

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

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

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

@ApiResponse： 描述操作的可能響應(yīng)。

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

@Authorization： 聲明要在資源或操作上使用的授權(quán)方案。

@AuthorizationScope： 描述OAuth2授權(quán)范圍。

@ResponseHeader： 表示可以作為響應(yīng)的一部分提供的標頭。

@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介紹

從本質(zhì)上講，Actuator為我們的應(yīng)用程序帶來了生產(chǎn)就緒功能。通過這種依賴關(guān)系監(jiān)控我們的應(yīng)用程序，收集指標，了解流量或數(shù)據(jù)庫的狀態(tài)變得微不足道。這個庫的主要好處是我們可以獲得生產(chǎn)級工具，而無需自己實際實現(xiàn)這些功能。Actuator主要用于公開有關(guān)正在運行的應(yīng)用程序的運行信息 - 運行狀況，指標，信息，轉(zhuǎn)儲，env等。它使用HTTP端點或JMX bean來使我們能夠與它進行交互。一旦這個依賴關(guān)系在類路徑上，就可以開箱即用幾個端點。與大多數(shù)Spring模塊一樣，我們可以通過多種方式輕松配置或擴展它。

注意事項

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

Actuator現(xiàn)在與技術(shù)無關(guān)，而在1.x中，它與MVC相關(guān)聯(lián)，因此與Servlet API相關(guān)聯(lián)。
在2.x中，Actuator定義了它的模型，可插拔和可擴展，而不依賴于MVC。因此，通過這個新模型，我們可以利用MVC和WebFlux作為底層Web技術(shù)。
此外，可以通過實施正確的適配器來添加即將到來的技術(shù)。
最后，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的相關(guān)依賴:

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)控的端口和路徑以及關(guā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的相關(guān)依賴，然后通過調(diào)用Actuator提供的一些接口就可以得知相關(guān)的信息。
這些接口的一些說明如下:

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

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

更多的相關(guān)配置說明可以查看官方文檔！

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

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

功能測試

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

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

示例圖：

對外提供的Actuator主要是可以幫助我們獲取一些程序以及一些環(huán)境的相關(guān)信息。

比如獲取程序健康狀態(tài)。

在瀏覽器輸入:

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

總結(jié)

以上所述是小編給大家介紹的SpringBoot整合Swagger和Actuator的使用教程詳解,希望對大家有所幫助，如果大家有任何疑問請給我留言，小編會及時回復(fù)大家的。在此也非常感謝大家對腳本之家網(wǎng)站的支持！
如果你覺得本文對你有幫助，歡迎轉(zhuǎn)載，煩請注明出處，謝謝！

最新評論