SpringBoot整合Swagger和Actuator

阿新 • • 發佈：2019-06-18

前言

本篇文章主要介紹的是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 可以得到配置生效資訊

/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專案實現檔案上傳和郵件傳送

音樂推薦

原創不易，如果感覺不錯，希望給個推薦！您的支援是我寫作的最大動力！
版權宣告:
作者：虛無境
部落格園出處：http://www.cnblogs.com/xuwujing
CSDN出處：http://blog.csdn.net/qazwsxpcm　　　　
個人部落格出處：http://www.panchengming.

SpringBoot整合Swagger和Actuator

前言

SpringBoot整合Swagger

Swagger 介紹

Swagger優缺點

優點

缺點

Swagger 相關地址

開發準備

程式碼編寫

功能測試

SpringBoot整合Actuator

Actuator介紹

注意事項

開發準備

程式碼編寫

功能測試

其它

專案地址

SpringBoot整合系列的文章

音樂推薦

相關推薦