快捷導(dǎo)航

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

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

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

1.0 Swagger 介紹

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

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

簡(jiǎn)單來(lái)說(shuō)，就是 Swagger 框架可以根據(jù)已經(jīng)實(shí)現(xiàn)的方法或者類，通過(guò)頁(yè)面的方式直觀清晰的查看或者進(jìn)行測(cè)試該方法。

1.1 Swagger 和 Yapi 的使用場(chǎng)景

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

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

2.0 Swagger 的使用方式

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

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

            <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)建一個(gè)配置類，在普通類上加上 @Configuration 注解，且該類需要繼承WebMvcConfigurationSupport 類。

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

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

代碼如下：

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

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

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

重寫配置類中的 addResourceHandlers 方法，通過(guò)該資源路徑"/doc.html" 來(lái)訪問(wèn)該頁(yè)面。

    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的配置代碼

 
/**
 * 配置類，注冊(cè)web層相關(guān)組件
 */
@Configuration
@Slf4j
public class WebMvcConfiguration extends WebMvcConfigurationSupport {
    /**
     * 通過(guò)knife4j生成接口文檔
     * @return
     */
    @Bean
    public Docket docket() {
        ApiInfo apiInfo = new ApiInfoBuilder()
                .title("項(xiàng)目接口文檔")
                .version("2.0")
                .description("項(xiàng)目接口文檔")
                .build();
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo)
                .select()
                .apis(RequestHandlerSelectors.basePackage("需要測(cè)試方法所在項(xiàng)目的包名"))
                .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/");
    }
}

具體的頁(yè)面效果：

通過(guò)訪問(wèn) "/doc.html" 的資源路徑，就可以訪問(wèn)到該頁(yè)面，通過(guò)該頁(yè)面就可以非常方便測(cè)試這些方法了。

補(bǔ)充：

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

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

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

3.0 Swagger 常見的注解

通過(guò)注解可以控制生成的接口文檔，使用接口文檔擁有更好的可讀性。簡(jiǎn)單來(lái)說(shuō)，通過(guò)這些注解就可以對(duì)類、方法、方法中的屬性進(jìn)行說(shuō)明，在測(cè)試方法的過(guò)程中，可以很清晰的明白該方法或者類的用途、信息。

常用注解如下：

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

代碼如下：

效果如下：

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

代碼如下：

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

效果如下：

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

代碼如下：

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

效果如下：

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

代碼如下：

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

效果如下：