SpringBoot項目中怎么使用Swagger2及注解解釋

本文小編為大家詳細介紹“SpringBoot項目中怎么使用Swagger2及注解解釋”，內容詳細，步驟清晰，細節處理妥當，希望這篇“SpringBoot項目中怎么使用Swagger2及注解解釋”文章能幫助大家解決疑惑，下面跟著小編的思路慢慢深入，一起來學習新知識吧。

一、導入Swagger坐標依賴

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>${swagger.version}</version>
</dependency>

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>${swagger.version}</version>
</dependency>

其中版本最常用2.9.2

二、在spring啟動類添加注解@EnableSwagger2

@EnableSwagger2是springfox提供的一個注解，代表swagger2相關技術開啟。會掃描當前類所在包，及子包中所有類型的swagger相關注解，做swagger文檔的定制

三、啟動項目，查看swaggerui.html界面

點擊try it out可以輸入對應的參數查看返回結果

四，編寫SwaggerConfig配置文件

@EnableSwagger2
@Configuration
public class SwaggerConfig {
    @Autowired
    private ApplicationContext applicationContext;

    private Contact contact = new Contact("NIUA","localhost:8080/swagger-ui.html", "1053288979@qq.com");

    @Bean
    public Docket createRestApi() {
        ServletContext servletContext = applicationContext.getBean(ServletContext.class);
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(Predicates.not(regex("/error.*")))
                .build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("平臺接口 v1.0")
                .description("平臺接口")
                .contact(contact)
                .version("1.0")
                .build();
    }
}

@Bean
    public Docket createRestApi() {
        ServletContext servletContext = applicationContext.getBean(ServletContext.class);
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(Predicates.not(regex("/error.*")))
                .build()
                .apiInfo(apiInfo());
    }

創建Docker類型的對象，并使用spring容器管理。Docker是Swagger中的全局配置對象

DocumentationType.SWAGGER_2：給Docket一個類對象，知道是那一個版本的

apiInfo()：API文檔的描述信息，參數是一個ApiInfo類對象，使用bulid()構建器來創建

private ApiInfo apiInfo() {
       return new ApiInfoBuilder()
               .title("平臺接口 v1.0")
               .description("平臺接口")
               .contact(contact)
               .version("1.0")
               .build();
   }

contact()：配置swagger文檔的主體內容，里面填寫也是一個類對象，類對象最多可以三個參數，發布者名稱，文檔發布者的網站url地址（企業網站），文檔發布者的電子郵箱地址

private Contact contact = new Contact("NIUA","localhost:8080/swagger-ui.html", "1053288979@qq.com");

title()：標題 description()：描述信息 .version()：版本信息

對應如下內容

select()：獲取Docker中的選擇器，返回ApiSelectorBuilder。構建選擇器。如掃描什么包的注解

apis()：后面是RequestHandlerSelectors的類下的(Predicate)規則，規定掃描那些包的注解，默認是啟動類及其子包下的注解

RequestHandlerSelectors類下有幾個靜態方法（舉例三個）

basePackage()：后面填寫包名的具體地址，會掃描改包及其子包的注解

docker.apis(RequestHandlerSelectors.basePackage("com.xxx"))

any()：為任何接口生成API文檔

none()：任何接口都不生成接口文檔

path()：使用正則表達式，約束生成Api文檔的路徑地址，后面填寫過濾（通過）的路徑

//過濾掉admin路徑下的所有頁面
.paths(Predicates.not(PathSelectors.regex("/admin/.*")))
//過濾掉所有error或error.*頁面
.paths(Predicates.not(PathSelectors.regex("/error.*")))

//所有error或error.*頁面或者admin路徑下的所有頁面都支持（or任意滿足起一就通過）
.paths(Predicates.or(PathSelectors.regex("/error.*"),PathSelectors.regex("/admin/.*")))

五：Swagger支持自定義注解

這里沒有提及，感興趣可以自己搜索（留個位置，日后用到了補充）

六：Swagger2常用注解

@Api(常用)

作用：@Api是類上注解。控制整個類生成接口信息的內容

屬性：

tags：類的名稱。可以有多個值，多個值表示多個副本（別名），有幾個別名在swaggerui視圖上顯示幾個控制器訪問菜單

description：描述，已過時

@ApiOperation

作用：@ApiOperation是方法上注解，描述方法的相關消息

屬性：

value：方法描述作用

notes：方法筆記（展開描述）

@ApiParm

作用：@ApiParm是方法參數的注解。描述該參數

屬性：

name：參數名稱

value：描述參數作用

required：值為boolean類型，表示該參數是否為必要參數，默認為false

@ApiIgnore

作用：@ApiParm是方法或者參數的注解。忽略注解的方法或者參數，不生成幫助文檔

@ApiImplicitParam(常用)

作用：@ApiParm是作用于類上方法，用來描述方法參數的注解。

屬性：

name：參數名稱，和方法的參數一致

value：參數具體描述

required：值為boolean類型，表示該參數是否為必要參數，默認為false

paramType：參數類型

paramType="字符串"
paramType = "header"

dataType：數據類型

dataType = "string"  //字符串數據
dataType = "鍵值對"

@ApiImplicitParams

后面跟@ApiImplicitParam的集合，一般用于多個參數的描述

@ApiImplicitParams({@ApiImplicitParam(name = "Authorization", value = "Authorization token", required = true, dataType = "string", paramType = "header")})

@ApiModel(常用)

作用：@ApiModel是作用于實體類上，描述一個實體類型，整個實體類型如果成為任何一個生成api幫助文檔的返回對象的時候，該注解被解析

屬性：

value：實體類名稱

description：實體類描述

@ApiModelProperty(常用)

作用：@ApiModel是作用于實體類的屬性上，描述實體類屬性

屬性：

value：實體屬性描述

name：實體類屬性名字，與屬性名一致

讀到這里，這篇“SpringBoot項目中怎么使用Swagger2及注解解釋”文章已經介紹完畢，想要掌握這篇文章的知識點還需要大家自己動手實踐使用過才能領會，如果想了解更多相關內容的文章，歡迎關注億速云行業資訊頻道。