Spring Boot 快速整合Swagger

一、前言

Spring Boot作為當前最為流行的Java web開發腳手架，越來越多的開發者選擇用其來構建企業級的RESTFul API接口。這些接口不但會服務於傳統的web端（b/s），也會服務於移動端。在實際開發過程中，這些接口還要提供給開發測試進行相關的白盒測試，那么勢必存在如何在多人協作中共享和及時更新API開發接口文檔的問題。

使用 Swagger 集成文檔具有以下幾個優勢：

• 功能豐富 ：支持多種注解，自動生成接口文檔界面，支持在界面測試API接口功能；
• 及時更新 ：開發過程中花一點寫注釋的時間，就可以及時的更新API文檔，省心省力；
• 整合簡單 ：通過添加pom依賴和簡單配置，內嵌於應用中就可同時發布API接口文檔界面，不需要部署獨立服務。

接下來，我們通過Spring Boot來整合Swagger實現在線API文檔的功能，本文用的是SpringFox Swagger2，版本2.9.2（最新版本是3.0.0，但是在我測試是swagger-ui.html頁面一直出不來，在https://mvnrepository.com/上也可以看到，2.9.2是目前使用最多的版本）

二、創建Spring Boot工程

我用的開發工具是IDEA，通過IDEA快速創建一個Spring Boot工程，創建時，只需勾選web依賴選項就成，不勾選也沒關系，后面在pom.xml中配置也是一樣的。注意創建工程時，工程名稱都要是小寫。

添加Swagger的兩個依賴

<!-- 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>

三、添加配置類

添加一個swagger 配置類，在工程下新建 config 包並添加一個 SwaggerConfig 配置類SwaggerConfig.java。

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

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

    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("在線API文檔")
                .description("This is a restful api document of demo")
                .version("1.0")
                .build();
    }

}

以上就已經完成了Swagger的配置，是不是很簡潔輕松。

四、創建一個測試Controller來驗證配置

添加一個控制器，在工程下新建 controller包並添加一個 HelloController控制器HelloController.java。

package com.louis.springboot.demo.controller;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;

/* 類注解 */
@Api
@RestController
public class HelloController {

    /* 方法注解 */
    @ApiOperation(value = "desc of method", notes = "")
    @GetMapping(value="/hello")
    public Object hello( @ApiParam(value = "desc of param" , required=true ) @RequestParam String name) {
        return "Hello " + name + "!";
    }
}

五、編譯運行測試

啟動工程， 打開瀏覽器，訪問：http://localhost:8080/swagger-ui.html，進入swagger接口文檔界面。

完畢收工，這樣管理API接口很方便，並且是和代碼實時更新的，不用煩心再去寫接口文檔啦。

附錄：Swagger常用注解

API	使用位置
@Api	用於controller類上，表示標識這個類是swagger的資源
@ApiOperation	用在controller的方法上，表示一個http請求的操作
@ApiParam	方法中的參數注釋
@ApiResponses	用在controller的方法上
@ApiResponse	用在 @ApiResponses里邊
@ApiImplicitParams	用在controller的方法上
@ApiImplicitParam	用在@ApiImplicitParams的方法里邊
@ApiModel	用在返回對象類上

WEB項目開發中碰到的問題千奇百怪，大家想了解對如何快速的掌握Spring Boot，可以參見視頻：

51CTO：Spring Boot+Bootstrap開發小而完整web項目
騰訊課堂：Spring Boot+Bootstrap開發小而完整web項目
CSDN學院：Spring Boot+Bootstrap開發小而完整web項目
網易雲課堂：Spring Boot+Bootstrap開發小而完整web項目