SpringBoot整合Swagger2產生介面文檔，媽媽再也不用擔心我寫API文檔了

在現在的開發過程中，基本上已經全部採用API 介面的方式進行系統的開發了，於是乎，在此過程中，一個好的API 文件便成為了後台與前台進行溝通與開發的關鍵橋樑。

    傳統的做法是由開發人員創建一份RESTful API 文件來記錄所有的介面細節，說實話，這樣的工作量並不小，而且十分瑣碎，且隨著專案的更新會出現以下問題。

• 文件難以維護。

• 介面內容更複雜，寫效率更低。

    Swagger 便是為了解決這個問題，它作為一個規格和完整的框架，可以用來產生、描述、呼叫和視覺化RESTful 風格的Web 服務：

    透過Swagger，我們可以在開發介面的過程中透過使用註解自動產生/更新API 介面文檔，且在文檔頁面支援介面的偵錯。

接下來就簡單說一下，如何在SpringBoot 中整合Swagger2(2 代表其版本)

引入Swagger2 依賴

pom.xml 文件

<dependencies>
        <!--Swagger2 在此，个人推荐使用2.8.0版本，较为稳定-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.8.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.8.0</version>
        </dependency>
</dependencies>

建立設定檔

Swagger2Config.java java 設定檔

@Configuration
// 指定扫描的api包路径
@ComponentScan(basePackages = {"cn.beatree.xxx.controller"})
//注解开启 swagger2 功能
@EnableSwagger2
public class Swagger2Config {
    @Value("${swagger2.enable}")
    boolean enable;
    // 配置文件中通过值注入控制生产环境与开发环境下的启用状态
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .enable(enable)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("ANONVOTE | Swagger API文档")//标题
                .description("description: ANONVOTE | Swagger API文档")//描述
                .contact("BEATREE")//作者信息
                .version("1.0.0")//版本号
                .build();
    }
}

application.yml 設定檔

swagger2:
  enable: false #true 启用

@Configuration 註解，指定為配置類，會在SpringBoot 啟動時進行載入。

@EnableSwagger2 註解來啟用 Swagger2。

成員方法 createRestApi 函數建立 Docket 的 Bean 之後，apiInfo() 用來創建該 Api 的基本資訊（這些基本資訊會展現在文件頁面中）。 select() 函數傳回一個 ApiSelectorBuilder 實例用來控制哪些介面暴露給 Swagger 來展現，本例採用指定掃描的套件路徑來定義，Swagger 會掃描該套件下所有 Controller 定義的 API，並產生文件內容（除了被 @ApiIgnore 指定的請求）。

常用Swagger 註解

@Api：修飾整個類，描述Controller 的作用

@ApiOperation：描述一個類別的一個方法，或者說一個介面

@ApiParam：單一參數描述@ApiModel：用物件來接收參數

@ApiProperty：用物件接收參數時，描述物件的一個欄位

@ApiResponse：HTTP 回應其中1 個描述

@ApiResponses：HTTP 回應整體描述

@ApiIgnore ：使用該註解忽略這個API

@ApiError ：發生錯誤回傳的訊息

@ApiImplicitParam：描述一個請求參數，可以配置參數的中文意義，也可以為參數設定預設值

@ApiImplicitParams：描述由多個

@ApiImplicitParam# 註解的參數所組成的請求參數清單

舉個栗子

@RestController
@Transactional    // 事务注解，实现回滚
@RequestMapping("/api/tlink")
@Api(value = "/api/tlink", tags = "参与者相关接口")
public class TlinkController{
    @GetMapping("/checkCode/{code}")
    @ApiOperation(value = "投票认证码核验接口",
            notes = "该接口用于核验认证码合法性，对于投票主题内容的获取需后续调用Topic相关接口。返回值data中带有参数 topic & options")
    public JSONObject checkCode(@PathVariable("code") String code){
  ...
 }
}

最後在執行SpringBoot 專案之後，透過伺服器位址/swagger-ui.html 存取即可。

要注意的是，如已新增路徑攔截器，需透過

.excludePathPatterns("/swagger-resources/**", "/webjars/**", "/v2/**", "/swagger-ui.html/**")

對 swagger 路徑放行。

以上是SpringBoot整合Swagger2產生介面文檔，媽媽再也不用擔心我寫API文檔了的詳細內容。更多資訊請關注PHP中文網其他相關文章！