如何在maven專案或者gradle專案中搭建swagger-本地測試工具

如何在maven專案或者gradle專案中搭建swagger-本地測試工具

Swagger是當前最好用的Restful API文件生成的開源專案，通過swagger-spring專案，實現了與SpingMVC框架的無縫整合功能，方便生成spring restful風格的介面文件， 同時swagger-ui還可以測試spring restful風格的介面功能。

1.在pom.xml中引入依賴

<!--Swagger本地測試介面工具  Swagger2核心包 -->
        <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>

如果是 gradle 專案則在 build.gradle檔案 中新增以下依賴 （maven 無視這一條）

dependencies {
	//    配置swagger
    compile group: 'io.springfox', name: 'springfox-swagger2', version: '2.9.2'
    compile group: 'io.springfox', name: 'springfox-swagger-ui', version: '2.9.2'
}

2.增加一個配置類

package org.sang.config;

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;

/**
 * @Author: XiaoPan
 * @CreateTime: 2020-10-20 21:26
 * Swagger 配置類
 */
@Configuration
@EnableSwagger2
public class SwaggerConfiguration {
    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.cy.Controler"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("Spring Boot中使用Swagger2構建RESTful APIs")
                .description("更多請關注http://www.baidu.com")
                .termsOfServiceUrl("http://www.baidu.com")
                .version("1.0")
                .licenseUrl("http://localhost:8091/")
                .build();
    }
}

3.最後在Controler層的所有介面中加上@ApiOperation註解即可

Swagger預設訪問地址：http://localhost:8080/swagger-ui.html#/

介面說明：

@Api：用在請求的類上，表示對類的說明

tags = “說明該類的作用，可以在UI介面上看到的註解”

value = “該引數沒什麼意義，在UI介面上也看到，所以不需要配置”

@ApiOperation 是用在方法上面的，又來說明介面

value = “介面說明”

httpMethod = “介面請求方式”

response = “介面返回引數型別”

notes = “介面釋出說明”

@ApiImplicitParams 用在方法上，用來給此方法一組引數的說明規定

單個引數用@ApiImplicitParam

多個就用@ApiImplicitParams({@ApiImplicitParam(xxxxxxxxxxxxxxx),@ApiImplicitParam(xxxxxxxxxxxxxxx),xxxxx}) 陣列集

paramType = “指定引數放何處” 值有以下幾種：

​ header ：請求引數放置於request header，使用@RequestHeader獲取

​ query：請求引數放置於地址中，使用@RequestParam獲取

​ path：這個結合restful風格使用時，用@PathVariable獲取

​ body：用@RequestBody獲取

​ form：不常用

@ApiParam註解屬性以及說明

required = “是否必須引數”

name = “引數名稱”

value = “引數具體描述”

@ApiResponses：用在請求的方法上，表示一組響應

@ApiResponse：用在@ApiResponses中，一般用於表達一個錯誤的響應資訊

code：數字，例如400

message：資訊，例如"請求引數沒填好"

response：丟擲異常的類

@ApiIgnore()用於類，方法，方法參數列示這個方法或者類被忽略