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() //為當(dāng)前包路徑 // .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ù)描述")
注意,當(dāng)同時存在@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)文章
Logger.getLogger()與LogFactory.getLog()的區(qū)別詳解
LogFactory來自common-logging包。如果用LogFactory.getLog,你可以用任何實現(xiàn)了通用日志接口的日志記錄器替換log4j,而程序不受影響2013-09-09Mybatis-plus新版本分頁失效PaginationInterceptor過時的問題
這篇文章主要介紹了Mybatis-plus新版本分頁失效,PaginationInterceptor過時問題,本文給大家介紹的非常詳細,對大家的學(xué)習(xí)或工作具有一定的參考借鑒價值,需要的朋友可以參考下2020-11-11Spring mvc是如何實現(xiàn)與數(shù)據(jù)庫的前后端的連接操作的?
今天給大家?guī)淼氖顷P(guān)于Spring mvc的相關(guān)知識,文章圍繞著Spring mvc是如何實現(xiàn)與數(shù)據(jù)庫的前后端的連接操作的展開,文中有非常詳細的介紹及代碼示例,需要的朋友可以參考下2021-06-06