快捷導(dǎo)航

Spring Boot中如何使用Swagger詳解

更新時(shí)間：2021年08月06日 11:55:58 作者：團(tuán)子大圓帥

Swagger是一個(gè)規(guī)范和完整的框架,用于生成、描述、調(diào)用和可視化 RESTful風(fēng)格的Web服務(wù),這篇文章主要給大家介紹了關(guān)于Spring Boot中如何使用Swagger的相關(guān)資料,需要的朋友可以參考下

Swagger 簡(jiǎn)介

Swagger 是一個(gè)方便 API 開(kāi)發(fā)的框架，它有以下優(yōu)點(diǎn)：

自動(dòng)生成在線文檔，后端開(kāi)發(fā)人員的改動(dòng)可以立即反映到在線文檔，并且不用單獨(dú)編寫(xiě)接口文檔，減輕了開(kāi)發(fā)負(fù)擔(dān)
支持通過(guò) Swagger 頁(yè)面直接調(diào)試接口，方便前端開(kāi)發(fā)人員進(jìn)行測(cè)試

配置 Swagger

Swagger 目前有 2.x 和 3.x 兩個(gè)主流版本，配置略有不同。

添加依賴

首先去 Maven 倉(cāng)庫(kù)中搜索 springfox 查找依賴的坐標(biāo)，Swagger 是遵循 OpenAPI 規(guī)范的技術(shù)，而 springfox 是該技術(shù)的一種實(shí)現(xiàn)，所以這里要搜 springfox 而不是 swagger。

對(duì)于 Swagger 2.x，需要在 pom.xml 中添加兩項(xiàng)配置：

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

對(duì)于 Swagger 3.x，簡(jiǎn)化了配置項(xiàng)，只需要在 pom.xml 中添加一項(xiàng)配置：

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-boot-starter -->
<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-boot-starter</artifactId>
  <version>3.0.0</version>
</dependency>

為項(xiàng)目開(kāi)啟 Swagger

對(duì)于 Swagger 2.x，使用 @EnableSwagger2 注解開(kāi)啟 Swagger 功能。

@EnableSwagger2
@SpringBootApplication
public class SwaggerApplication {
    ...
}

對(duì)于 Swagger 3.x，使用 @EnableOpenApi 注解開(kāi)啟 Swagger 功能。

@EnableOpenApi
@SpringBootApplication
public class SwaggerApplication {
    ...
}

創(chuàng)建 SwaggerConfig 配置類(lèi)

對(duì)于 Swagger 2.x，實(shí)例化 Docket 的時(shí)候，需要傳入 DocumentationType.SWAGGER_2。
對(duì)于 Swagger 3.x，實(shí)例化 Docket 的時(shí)候，需要傳入 DocumentationType.OAS_30。

下面是一份配置模板：

import org.springframework.beans.factory.annotation.Value;
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.*;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
public class SwaggerConfig {

    @Value("${spring.profiles.active:NA}")
    private String active;

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)  // OAS_30
                .enable("dev".equals(active))  // 僅在開(kāi)發(fā)環(huán)境開(kāi)啟Swagger
                .apiInfo(apiInfo())
                .host("http://www.example.com")  // Base URL
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("API文檔")
                .description("這是描述信息")
                .contact(new Contact("張三", null, null))
                .version("1.0")
                .build();
    }
}

訪問(wèn) Swagger 前端頁(yè)面

對(duì)于 Swagger 2.x，訪問(wèn) http://localhost:8080/swagger-ui.html
對(duì)于 Swagger 3.x，訪問(wèn) http://localhost:8080/swagger-ui/

控制器相關(guān)注解

@Api：將一個(gè)類(lèi)標(biāo)記為 Swagger 資源，一般放在 Controller 類(lèi)上面，通過(guò) tags 指定描述信息，比如 @Api(tags="用戶管理")。

@ApiOperation：本注解放在 Controller 方法上面，描述該方法的作用。

@ApiParam：本注解放在 Controller 方法的形參前面，可以描述參數(shù)的作用，比如 @ApiParam("用戶名") String username。可以使用 value 指定描述信息，通過(guò) required = true 指定必需傳遞該參數(shù)。

package com.example.swagger.controller;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@Api(tags = "Hello控制器")
@RestController
public class HelloController {
    @ApiOperation("展示歡迎信息")
    @GetMapping("/hello")
    public String hello(@ApiParam("名字") String name) {
        return "hello, " + name;
    }
}

實(shí)體相關(guān)注解

@ApiModel：一般放在實(shí)體類(lèi)上面。可以通過(guò) value 指定別名，不指定時(shí)默認(rèn)為類(lèi)名。還可以通過(guò) description 指定詳細(xì)的描述信息。比如 @ApiModel("用戶") 就將顯示用戶而不是 User。

![](cdn.jsdelivr.net/gh/jpch89/P… 在 Spring Boot 中使用 Swagger 00.png)
如果僅僅想指定描述，而不改變?cè)碱?lèi)名顯示，可以寫(xiě)成 @ApiModel(description = "用戶")。

@ApiModelProperty：一般放在實(shí)體類(lèi)的成員變量上面，通過(guò) value 指定描述信息，example 指定示例數(shù)據(jù)，required = true 指定該參數(shù)是必需的，hidden = true 用于隱藏該字段，不會(huì)在 API 文檔中顯示。

package com.example.swagger.pojo;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

@Data
@ApiModel(description = "用戶")
public class User {
    @ApiModelProperty("用戶名")
    private String username;
    @ApiModelProperty("密碼")
    private String password;
    @ApiModelProperty(value = "年齡", example = "18", required = true)
    private int age;
    @ApiModelProperty(hidden = true)
    private double money;
}