全面介紹Swagger介面文檔工具

一、Swagger是什麼？

Swagger是一套開源的API文檔工具，它能夠為RESTful Services自動生成API文檔，還能提供在線API測試功能，並且生成客戶端的API SDK。Swagger最初是由Tony Tam在2011年創建的。從那以後，Swagger已經發展成為一個極受歡迎的API文檔工具。
Swagger 在其生命周期內經過了許多變化，從Swagger 1.2 到 Swagger 2.0，直到成為 OpenAPI ，而這個變化也可以解釋為許多人按照之前的 Apache 2.0 許可證核心創建了該項目。

二、Swagger的核心維度

在 Swagger 之中，有三個核心維度：

Swagger Spec：該規範定義了使用 JSON 或 YAML 的 APIs 描述文件的結構。它支持 RESTful APIs 的描述，使得 RESTful APIs 的定義和使用更加簡單和規範。

Swagger Editor：Swagger Editor 是一個用於編輯 Swagger API 設計的工具。通過簡單而強大的編輯器，它可以幫助用戶輕鬆創建，編輯和維護 Swagger API 規範。

Swagger UI：Swagger UI 允許用戶通過瀏覽器來互動式的查看和試驗 API 文檔。 用戶可以通過一個界面來測試 API 的各個端點，而不需要終端或第三方應用程序支持。

三、如何使用Swagger?

下面我們將介紹如何在Spring Boot應用程序中使用Swagger。

1. 添加Swagger依賴項

 <dependency>
     <groupId>io.springfox</groupId>
     <artifactId>springfox-swagger2</artifactId>
     <version>2.9.2</version>
 </dependency>
 
 <dependency>
     <groupId>io.springfox</groupId>
     <artifactId>springfox-swagger-ui</artifactId>
     <version>2.9.2</version>
 </dependency>

2. 啟用Swagger

啟用Swagger 需要添加@Configuration註解，以便將Swagger添加為一個 Spring Bean。這可以通過在應用程序中創建 @Bean 聲明方式來完成。

package com.example.demo;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
@EnableWebMvc
public class SwaggerConfig extends WebMvcConfigurerAdapter {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }
}

3. 使用Swagger來注釋APIs

上面的配置讓你能夠查看你 Spring Boot 項目中的所有 API 列表，但是如果你想為 API 添加更多的描述、tags 和請求示例，那就需要添加更多的注釋了。簡單地把Swagger掃描過的範圍配置在所有@RequestMapping註解的方法上，並在註解中描述每個特定的API。

@RestController
@RequestMapping("/user")
public class UserController {

    @ApiOperation(value = "獲取用戶詳細信息", notes = "根據url的id來獲取用戶詳細信息")
    @ApiImplicitParam(name = "id", value = "用戶ID", required = true, dataType = "Long", paramType = "path")
    @RequestMapping(value = "/{id}", method = RequestMethod.GET)
    public User getUserById(@PathVariable(value = "id") Long id) {
        // ...
    }

    @ApiOperation(value = "添加用戶", notes = "根據User對象創建用戶")
    @ApiImplicitParam(name = "user", value = "用戶詳細實體user", required = true, dataType = "User")
    @RequestMapping(value = "/add", method = RequestMethod.POST)
    public String addUser(@RequestBody User user) {
        // ...
    }
}

四、Swagger界面展示與說明

Swagger UI 是 Swagger 最突出的特點之一。它提供了一個易於使用 Web 介面來查看、測試和文檔化 API。Swagger UI 是Swagger規範的 HTML/CSS/JavaScript 體現形式。因此，您可以將這個界面引入到您的現有項目中，以測試您的 API。

最常見的 Swagger UI 是內置在 Swagger-editor 工具中提供的 UI。該 UI 允許您可視化定義您的 API 並文檔化您的 API 存儲庫。

通過在 Web 瀏覽器中導航到 Swagger UI 項目並選擇並輸入一個 OpenAPI（以 Swagger 2.0兼容體驗） 規範註冊表，您可以將Swagger UI 與您的 API 對接，從而創造一個互動式的 API 文檔和操作界面。

效果如圖所示：

<img src="https://img-blog.csdn.net/20171025225006921?watermark/2/text/aHR0cDovL2Jsb2cuY3Nkbi5uZXQvZ3Vvb25nZW43MjUx/font/5a6L5L2T/fontsize/400/fill/I0JBQkFCMA==/dissolve/70/q/75"
  alt="SwaggerUI"
  title="SwaggerUI"
  style="display:block;margin:auto;width:80%;">