SpringBoot項目集成Swagger和swagger-bootstrap-ui及常用注解有哪些

本篇內容介紹了“SpringBoot項目集成Swagger和swagger-bootstrap-ui及常用注解有哪些”的有關知識，在實際案例的操作過程中，不少人都會遇到這樣的困境，接下來就讓小編帶領大家學習一下如何處理這些情況吧！希望大家仔細閱讀，能夠學有所成！

一、前言

隨著互聯網項目前后端分離方式的流行，前端與后端交給不同的人員開發，項目溝通成本也隨之提高。

主要表現在WebAPI接口的溝通，Swagger2 應運而生，它可以動態生成Api接口文檔，降低溝通成本，促進項目高效開發。

下面討論Swagger2及swagger-bootstrap-ui在SpringBoot上的集成

二、SpringBoot項目集成swagger

1. 引入依賴

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.8.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.8.0</version>
        </dependency>

2. 編寫配置文件

可對照進行相應的修改

@Configuration
@EnableSwagger2
@EnableSwaggerBootstrapUI
@Profile({"dev","test"})
public class Swagger2Config {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("") //指定分組，對應(/v2/api-docs?group=)
                .pathMapping("") //base地址，最終會拼接Controller中的地址
                .apiInfo(apiInfo())
                .select()
                //為當前包路徑
				// .apis(RequestHandlerSelectors.any())
                .apis(RequestHandlerSelectors.basePackage("com.riskeys.sd.custom"))
                .paths(PathSelectors.any())
                .build();
    }

    //構建 api文檔的詳細信息函數
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //頁面標題
                .title("XXX API對接文檔")
                .description("XX API對接文檔") //描述
                //創建人
                .contact(new Contact("yuhei001", "https://blog.csdn.net/Yuhei0", "18616591658@163.com"))
                //版本號
                .version("1.0")
                //描述
                .description("API 描述")
                .build();
    }
}

3. 啟動訪問頁面

http://127.0.0.1:10086/swagger-ui.html

三、SpringBoot項目集成swagger-bootstrap-ui

在步驟二的基礎上進行如下操作

1.引入依賴

        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.6</version>
        </dependency>

2.配置資源處理規則

未配置的情況下，有可能訪問報error.9996。

實現WebMvcConfigurer接口，或者WebMvcConfigurationSupport(老版的SpringBoot)，實現addResourceHandlers方法，加上如下所示代碼即可。

@Configuration
public class AppWebConfig extends WebMvcConfigurationSupport{

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        // 解決 doc.html 404 報錯
        registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }

}

或者

@Configuration
public class AppWebConfig extends WebMvcConfigurationSupport{
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        // 解決 doc.html 404 報錯
        registry.addResourceHandler("doc.html").addResourceLocations("classpath*:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath*:/META-INF/resources/webjars/");
    }
}

另外，也可以在啟動類上進行實現重寫

@SpringBootApplication
public class XXXApplication  implements WebMvcConfigurer{
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("doc.html").addResourceLocations("classpath*:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath*:/META-INF/resources/webjars/");
    }
}

3.啟動訪問頁面

訪問http://127.0.0.1:10086/doc.html，相較swagger-ui.html來說，此文檔更為清爽。

四、Swagger常用注解介紹

swagger通過注解生成接口文檔，包括接口名、請求方法、參數、返回信息等等。

1.Swagger2Config中相關swagger注解

1.1 @EnableSwagger2 開啟Swagger

作用于配置類或啟動類

1.2 @EnableSwaggerBootstrapUI 開啟SwaggerBootstrapUi增強功能

作用于配置類或啟動類，如果不使用增強功能，可不開啟。

2.controller中相關swagger注解

2.1 @Api：修飾整個類，描述Controller的作用

value和tags均為說明，可用tags代替value

@Api(value = "保險公司列表查詢", tags = {"保險公司列表查詢"})

2.2 @ApiOperation() 用于方法；表示一個http請求的操作

@ApiOperation(value = "信息員保存(注冊)/更新", tags = {"信息員保存"}, notes = "messenger desc")

2.3 @ApiParam 用于方法，參數，字段說明；表示對參數的添加元數據（說明或是否必填等）

適用于單個參數

@ApiParam(name="sdMessengerInfo",value="參數描述",required=true)

2.4 請求參數注解，可進行組合

• @ApiImplicitParams 用于方法，包含多個 @ApiImplicitParam

• @ApiImplicitParam 用于方法，表示單獨的請求參數

適用于對多個參數進行描述

示例：

// 組合使用
@ApiImplicitParams ({
    @ApiImplicitParam(name = "id", value = "參數中文描述", required = true)
})
// 單獨使用
@ApiImplicitParam(paramType="query", name="id", dataType="String", required=true, value="參數描述")

注意，當同時存在@ApiParam和@ApiImplicitParam時，以@ApiImplicitParam的描述為準。

2.5 @ApiIgnore() 用于類或者方法上，可以不被swagger顯示在頁面上 ,使用較少。

2.6 響應配置

• @ApiResponses

• @ApiResponse

// 單獨配置
@ApiResponse(code = 400, message = "Invalid user supplied")
// 組合使用
@ApiResponses({ @ApiResponse(code = 400, message = "Invalid Order") })

2.7 @ResponseHeader 響應頭設置

@ResponseHeader(name="head1",description="response head conf")

3.Model中相關swagger注解

3.1 @ApiModel 用于類 ；表示對類進行說明，用于參數用實體類接收。

@ApiModel(value = "demo", description = "對象描述")

一般value和desc可以省略不寫

3.2 @ApiModelProperty 用于方法，字段； 表示對model屬性的說明或者數據操作更改

@ApiModelProperty(value = "用戶id",name = "openid2",dataType = "String", required = true, hidden = true)

• value–字段說明

• name–重寫屬性名字

• dataType–重寫屬性類型

• required–是否必填

• example–舉例說明

• hidden–隱藏

一般只對value，required進行標示。

“SpringBoot項目集成Swagger和swagger-bootstrap-ui及常用注解有哪些”的內容就介紹到這里了，感謝大家的閱讀。如果想了解更多行業相關的知識可以關注億速云網站，小編將為大家輸出更多高質量的實用文章！