快捷導(dǎo)航

SpringBootWeb?入門了解?Swagger?的具體使用

更新時間：2024年08月07日 12:24:07 作者：小扳

這篇文章主要介紹了SpringBootWeb?入門了解?Swagger?的具體使用,Swagger?框架可以根據(jù)已經(jīng)實現(xiàn)的方法或者類,通過頁面的方式直觀清晰的查看或者進行測試該方法,需要的朋友可以參考下

1.0 Swagger 介紹

使用 Swagger 你只需要按照它的規(guī)范去定義接口及接口相關(guān)的信息，就可以做到生成接口文檔，以及在線接口調(diào)試頁面。

knife4j 是為 Java MVC 框架集成 Swagger 生成 Api 文檔的增強解決方案。Swagger 允許定義 API 的各種方面，包括輸入?yún)?shù)、請求和響應(yīng)的數(shù)據(jù)格式、接口路徑等內(nèi)容。同時， Swagger 提供了一個交互式的 Swagger UI ，可以直觀地查看和測試 API 。

簡單來說，就是 Swagger 框架可以根據(jù)已經(jīng)實現(xiàn)的方法或者類，通過頁面的方式直觀清晰的查看或者進行測試該方法。

1.1 Swagger 和 Yapi 的使用場景

1）Yapi 是設(shè)計階段使用的工具，管理和維護接口。

2）Swagger 在開發(fā)階段使用的框架，幫助后端開發(fā)人員的接口測試。

2.0 Swagger 的使用方式

首先通過導(dǎo)入 knife4j 的 maven 坐標，再在配置類中加入 knife4j 相關(guān)配置，最后設(shè)置靜態(tài)資源映射。

2.1 導(dǎo)入 knife4j 的 maven 坐標

            <dependency>
                <groupId>com.github.xiaoymin</groupId>
                <artifactId>knife4j-spring-boot-starter</artifactId>
                <version>3.0.2</version>
            </dependency>

2.2 在配置類中加入 knife4j 相關(guān)配置

首先創(chuàng)建一個配置類，在普通類上加上 @Configuration 注解，且該類需要繼承WebMvcConfigurationSupport 類。

再定義一個返回 Docket 的 docket 方法，且該方法需要加上 @Bean 注解，使其交給 IOC 容器管理，成為 Bean 對象。

在該 docket 方法中先創(chuàng)建一個 ApiInfo 對象，通過 apiInfo 的一些方法來設(shè)置屬性，再創(chuàng)建一個 Docket 對象，通過 docket 的一些方法來設(shè)置屬性，再將設(shè)置好的 docket 對象返回。

代碼如下：

    @Bean
    public Docket docket() {
        ApiInfo apiInfo = new ApiInfoBuilder()
                .title("項目接口文檔")
                .version("2.0")
                .description("項目接口文檔")
                .build();
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo)
                .select()
                .apis(RequestHandlerSelectors.basePackage("需要掃描的項目名"))
                .paths(PathSelectors.any())
                .build();
        return docket;
    }

其中設(shè)置apis(RequestHandlerSelectors.basePackage("需要掃描的項目名")) 該屬性是很重要的，項目中要測試的方法或者類在具體包的包名。這樣就會自動掃描該包及其子包的方法或者類。

2.3 設(shè)置靜態(tài)資源映射，否則接口文檔頁面無法訪問

重寫配置類中的 addResourceHandlers 方法，通過該資源路徑"/doc.html" 來訪問該頁面。

    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }

2.4 完整Swagger的配置代碼

 
/**
 * 配置類，注冊web層相關(guān)組件
 */
@Configuration
@Slf4j
public class WebMvcConfiguration extends WebMvcConfigurationSupport {
    /**
     * 通過knife4j生成接口文檔
     * @return
     */
    @Bean
    public Docket docket() {
        ApiInfo apiInfo = new ApiInfoBuilder()
                .title("項目接口文檔")
                .version("2.0")
                .description("項目接口文檔")
                .build();
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo)
                .select()
                .apis(RequestHandlerSelectors.basePackage("需要測試方法所在項目的包名"))
                .paths(PathSelectors.any())
                .build();
        return docket;
    }
    /**
     * 設(shè)置靜態(tài)資源映射
     * @param registry
     */
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

具體的頁面效果：

通過訪問 "/doc.html" 的資源路徑，就可以訪問到該頁面，通過該頁面就可以非常方便測試這些方法了。

補充：

若要使用 .built 來創(chuàng)建對象，你需要導(dǎo)入 Lombok 這個庫的 Maven 坐標。在 Maven 項目中，你可以在 pom.xml 文件中添加以下依賴項：

<dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
    <version>1.18.20</version>
</dependency>

實際上，使用.builder創(chuàng)建對象是針對 Lombok 中的@Builder注解的功能。要使用 Lombok 的@Builder注解創(chuàng)建對象，你需要在你的Java類中添加@Builder注解，而不是導(dǎo)入特定的 Lombok 庫的 Maven 坐標。

3.0 Swagger 常見的注解

通過注解可以控制生成的接口文檔，使用接口文檔擁有更好的可讀性。簡單來說，通過這些注解就可以對類、方法、方法中的屬性進行說明，在測試方法的過程中，可以很清晰的明白該方法或者類的用途、信息。

常用注解如下：

1）@Api("tags=對類的描述")：用在類上，比如 Controller ，表示對類的說明。

代碼如下：

效果如下：

2）@ApiModel(description="對實體類進行描述")：用在實體類上，比如 entity、DTO、VO 。

代碼如下：

@Data
@ApiModel(description = "員工登錄時傳遞的數(shù)據(jù)模型")
public class EmployeeLoginDTO implements Serializable {
    @ApiModelProperty("用戶名")
    private String username;
    @ApiModelProperty("密碼")
    private String password;
}

效果如下：

3）@ApiModelProperty("對屬性進行描述")：用在屬性上，描述屬性信息。

代碼如下：

@Data
@ApiModel(description = "員工登錄時傳遞的數(shù)據(jù)模型")
public class EmployeeLoginDTO implements Serializable {
    @ApiModelProperty("用戶名")
    private String username;
    @ApiModelProperty("密碼")
    private String password;
}

效果如下：

4）@ApiOperation("對方法進行描述")：用在方法上，例如 Controller 的方法，說明方法的用途、作用。

代碼如下：

    @PostMapping
    @ApiOperation("新增員工")
    public Result<String> save(@RequestBody EmployeeDTO employeeDTO){
        log.info("新增員工");
        employeeService.save(employeeDTO);
        return Result.success();
    }

效果如下：