Spring Boot 快速整合Swagger

江成軍發表於2021-11-09
Spring BootSwagger

一、前言

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專案

相關文章