Spring Boot 快速整合Swagger

江成軍發表於2021-11-09

一、前言

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

相關文章