SpringBoot項目集成Swagger和swagger-bootstrap-ui及常用注解解讀
一、前言
隨著互聯(lián)網(wǎng)項目前后端分離方式的流行，前端與后端交給不同的人員開發(fā)，項目溝通成本也隨之提高。
主要表現(xiàn)在WebAPI接口的溝通，Swagger2 應(yīng)運而生，它可以動態(tài)生成Api接口文檔，降低溝通成本，促進項目高效開發(fā)。
下面討論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. 編寫配置文件
可對照進行相應(yīng)的修改
@Configuration
@EnableSwagger2
@EnableSwaggerBootstrapUI
@Profile({"dev","test"})
public class Swagger2Config {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.groupName("") //指定分組，對應(yīng)(/v2/api-docs?group=)
.pathMapping("") //base地址，最終會拼接Controller中的地址
.apiInfo(apiInfo())
.select()
//為當前包路徑
// .apis(RequestHandlerSelectors.any())
.apis(RequestHandlerSelectors.basePackage("com.riskeys.sd.custom"))
.paths(PathSelectors.any())
.build();
}
//構(gòu)建 api文檔的詳細信息函數(shù)
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
//頁面標題
.title("XXX API對接文檔")
.description("XX API對接文檔") //描述
//創(chuàng)建人
.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
在步驟二的基礎(chǔ)上進行如下操作
1.引入依賴
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.9.6</version>
</dependency>
2.配置資源處理規(guī)則
未配置的情況下，有可能訪問報error.9996。
實現(xiàn)WebMvcConfigurer接口，或者WebMvcConfigurationSupport(老版的SpringBoot)，實現(xiàn)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/");
}
}
另外，也可以在啟動類上進行實現(xiàn)重寫
@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通過注解生成接口文檔，包括接口名、請求方法、參數(shù)、返回信息等等。
1.Swagger2Config中相關(guān)swagger注解
1.1 @EnableSwagger2 開啟Swagger
作用于配置類或啟動類
1.2 @EnableSwaggerBootstrapUI 開啟SwaggerBootstrapUi增強功能
作用于配置類或啟動類，如果不使用增強功能，可不開啟。
2.controller中相關(guān)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 用于方法，參數(shù)，字段說明；表示對參數(shù)的添加元數(shù)據(jù)（說明或是否必填等）
適用于單個參數(shù)
@ApiParam(name="sdMessengerInfo",value="參數(shù)描述",required=true)
2.4 請求參數(shù)注解，可進行組合
- @ApiImplicitParams 用于方法，包含多個 @ApiImplicitParam
- @ApiImplicitParam 用于方法，表示單獨的請求參數(shù)
適用于對多個參數(shù)進行描述
示例：
// 組合使用
@ApiImplicitParams ({
@ApiImplicitParam(name = "id", value = "參數(shù)中文描述", required = true)
})
// 單獨使用
@ApiImplicitParam(paramType="query", name="id", dataType="String", required=true, value="參數(shù)描述")
注意，當同時存在@ApiParam和@ApiImplicitParam時，以@ApiImplicitParam的描述為準。
2.5 @ApiIgnore() 用于類或者方法上，可以不被swagger顯示在頁面上 ,使用較少。
2.6 響應(yīng)配置
- @ApiResponses
- @ApiResponse
// 單獨配置
@ApiResponse(code = 400, message = "Invalid user supplied")
// 組合使用
@ApiResponses({ @ApiResponse(code = 400, message = "Invalid Order") })
2.7 @ResponseHeader 響應(yīng)頭設(shè)置
@ResponseHeader(name="head1",description="response head conf")
3.Model中相關(guān)swagger注解
3.1 @ApiModel 用于類 ；表示對類進行說明，用于參數(shù)用實體類接收。
@ApiModel(value = "demo", description = "對象描述")
一般value和desc可以省略不寫
3.2 @ApiModelProperty 用于方法，字段； 表示對model屬性的說明或者數(shù)據(jù)操作更改
@ApiModelProperty(value = "用戶id",name = "openid2",dataType = "String", required = true, hidden = true)
value–字段說明name–重寫屬性名字dataType–重寫屬性類型required–是否必填example–舉例說明hidden–隱藏
一般只對value，required進行標示。
總結(jié)
以上，即為SpringBoot集成Swagger、swagger-bootstrap-ui以及Swagger常用注解相關(guān)介紹。
僅為個人經(jīng)驗，希望能給大家一個參考，也希望大家多多支持腳本之家。
相關(guān)文章
這篇文章主要介紹了Jmeter結(jié)構(gòu)體系及運行原理順序解析,文中通過示例代碼介紹的非常詳細，對大家的學(xué)習(xí)或者工作具有一定的參考學(xué)習(xí)價值,需要的朋友可以參考下2020-09-09
Java 注解（Annotation）又稱 Java 標注，是 JDK5.0 引入的一種注釋機制，文中給大家介紹了三種基本的Annotaton，本文給大家介紹的非常詳細，對大家的學(xué)習(xí)或工作具有一定的參考借鑒價值，需要的朋友參考下吧2022-05-05
Java關(guān)鍵字synchronized基本使用詳解
這篇文章主要給大家介紹了關(guān)于Java關(guān)鍵字synchronized基本使用的相關(guān)資料,synchronized可以用來同步靜態(tài)和非靜態(tài)方法,文中通過代碼介紹的非常詳細,需要的朋友可以參考下2024-01-01
這篇文章主要介紹了精通Java List 按字段提取對象的相關(guān)資料,需要的朋友可以參考下2023-11-11
利用Thumbnailator輕松實現(xiàn)圖片縮放、旋轉(zhuǎn)與加水印
java開發(fā)中經(jīng)常遇到對圖片的處理，JDK中也提供了對應(yīng)的工具類，不過處理起來很麻煩，Thumbnailator是一個優(yōu)秀的圖片處理的開源Java類庫,處理效果遠比Java API的好，這篇文章主要介紹了利用Thumbnailator如何輕松的實現(xiàn)圖片縮放、旋轉(zhuǎn)與加水印，需要的朋友可以參考下2017-01-01
文章介紹了三種創(chuàng)建線程的方式：繼承Thread類、實現(xiàn)Runnable接口和實現(xiàn)Callable接口,并比較了它們之間的區(qū)別和優(yōu)缺點2025-01-01
這篇文章主要介紹了maven配置文件pom增加變量取版本號方式，具有很好的參考價值，希望對大家有所幫助。如有錯誤或未考慮完全的地方，望不吝賜教2021-12-12
這篇文章主要介紹了Spring Boot webflux使用方法解析,文中通過示例代碼介紹的非常詳細，對大家的學(xué)習(xí)或者工作具有一定的參考學(xué)習(xí)價值,需要的朋友可以參考下2020-03-03
在本篇文章里小編給大家整理的是關(guān)于JavaWeb中文編碼問題方法的相關(guān)知識點內(nèi)容，需要的朋友們參考下2019-09-09
本文詳細介紹了Mybatis映射文件的結(jié)構(gòu)、標簽和使用方法,包括mapper元素、標簽的主要屬性如id、parameterType、resultType以及動態(tài)SQL和結(jié)果映射的使用,通過映射文件,可以將數(shù)據(jù)庫表與Java對象映射,支持查詢、插入、更新、刪除等操作,提高了SQL語句的靈活性和可重用性2024-09-09