【Spring Boot】快速整合Swagger

kamier發表於2022-12-31
Spring BootSwagger

一、引言

swagger是當下較流行的生成Api文件的工具，在實際開發過程中，前後端開發基於Api文件來進行對接聯調，而有一個好的Api文件對提升工作效率至關重要。大多數程式設計師是不太喜歡寫文件的，比如我，而swagger很好地幫助我們解決了這個問題，透過一些簡單配置，就可以幫助開發人員生成Api文件，接下來介紹Spring Boot工程如何來快速整合Swagger。

這裡我使用的Spring Boot版本：2.5.14

二、快速整合

2.1 pom引入swagger依賴

在pom檔案中引入swagger依賴，這裡使用版本2.7.0，如下

<!-- 整合swagger -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.7.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.7.0</version>
</dependency>

2.2 定義配置類

配置類上新增註解@EnableSwagger2，說明啟用swagger，配置類示例如下

/**
 * Description: SwaggerConfiguration
 * Created by kamier on 2022/12/28 22:06
 */

@Configuration
@EnableSwagger2
public class SwaggerConfiguration {

    /**
     * 文件定義
     * @return
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)  // 文件型別
                .apiInfo(apiInfo()) // api資訊
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.kamier.springboot.swagger")) // 選擇基礎路徑來需要生成api
                .paths(PathSelectors.any()) // 匹配某些路徑，比如/user/*
                .build()
                .globalOperationParameters(setHeaderToken());   // 新增全域性引數

    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("action-swagger")
                .description("api文件1")
                .termsOfServiceUrl("")
                .version("1.0")
                .build();
    }

    /**
     * 設定swagger文件中全域性引數
     */
    private List<Parameter> setHeaderToken() {
        List<Parameter> params = new ArrayList<>();
        ParameterBuilder parameterBuilder = new ParameterBuilder();
        Parameter parameter = parameterBuilder.name("token")
                .description("使用者token")
                .modelRef(new ModelRef("string"))
                .parameterType("header")
                .required(true)
                .build();
        params.add(parameter);
        return params;
    }
}

2.3 編寫Controller、實體類

編寫一個簡單Controller，用於測試，程式碼如下

@Api(tags = "測試api")
@RestController
@RequestMapping("/swagger")
public class SwaggerController {

    @ApiOperation("測試介面1")
    @PostMapping("/test")
    R<User> testSwagger(@RequestBody User user) {
        User user1 = new User()
                .setName("zhangsan")
                .setAge(25)
                .setStudent(false)
                .setSex(1)
                .setTel("138xxxxxxxx");
        return R.ok(user1);
    }
}

這裡的@Api和@ApiOperation是swagger的註解，用以描述介面資訊，並且可以看到介面的引數和返回值都用到了User類，User類程式碼如下

@Data
@Accessors(chain = true)
@ApiModel("使用者實體")
public class User {
    @ApiModelProperty(value = "姓名", notes = "筆記", required = true)
    private String name;

    @ApiModelProperty(value = "年齡")
    private int age;

    @ApiModelProperty(value = "性別 1男 2女")
    private int sex;

    @ApiModelProperty(value = "是否學生")
    private boolean isStudent;

    @ApiModelProperty(value = "手機號", hidden = true)
    private String tel;
}

@ApiModel和@ApiModelProperty也是swagger的註解，用於描述實體以及實體屬性。

2.4 專案啟動

至此，一個最簡單的Spring Boot整合swagger的樣例就完成了。

接下來我們來啟動專案（Spring Boot版本如果在2.6.x及以上，可能啟動過程中會報 "Failed to start bean 'documentationPluginsBootstrapper'"異常，將Spring Boot版本改為2.5.x及以下即可），啟動之後訪問http://localhost:8081/swagger-ui.html，如果訪問出現404，可以在WebMvcConfigurer中新增靜態資源處理，程式碼如下

@Configuration
public class WebMvcConfig implements WebMvcConfigurer {
    
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
        // 這個是後面切換ui介面的時候使用的
        registry.addResourceHandler("doc.html")
                .addResourceLocations("classpath:/META-INF/resources/");
    }
}

訪問成功的頁面如下

點開/swagger/test這個介面，可以看到如下頁面

  1. header中的token是我們在SwaggerConfiguration中配置的全域性引數，所有介面的請求頭都會帶上這個token
  2. 點選返回值和引數的Model按鈕，可以看到實體的屬性名稱、型別及說明，前端開發根據這個就可以知道介面需要的引數或介面所要返回的資料是什麼樣的

2.5 UI替換

swagger自身的這種ui介面風格不太直觀，在我們平時工作中，用的是另外一種介面，我們只需要引入一個依賴即可，如下

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.6</version>
</dependency>

引入之後，重新啟動專案，訪問http://localhost:8081/doc.html，頁面如下

到這裡，整個swagger的快速整合就全部結束了

相關文章