您好,登錄后才能下訂單哦!
集成swagger
pom包配置
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency> <!-- swagger-ui --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>${swagger.version}</version> </dependency>
添加Swagger配置文件
@Configuration @EnableSwagger2 public class SwaggerConfig { /** * 創(chuàng)建一個(gè)Docket對(duì)象 * 調(diào)用select()方法, * 生成ApiSelectorBuilder對(duì)象實(shí)例,該對(duì)象負(fù)責(zé)定義外漏的API入口 * 通過(guò)使用RequestHandlerSelectors和PathSelectors來(lái)提供Predicate,在此我們使用any()方法,將所有API都通過(guò)Swagger進(jìn)行文檔管理 * @return */ @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.any()) .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() //標(biāo)題 .title("Spring Boot中使用Swagger2構(gòu)建RESTful APIs") //簡(jiǎn)介 .description("") //服務(wù)條款 .termsOfServiceUrl("") //作者個(gè)人信息 .contact(new Contact("chenguoyu","","chenguoyu_sir@163.com")) //版本 .version("1.0") .build(); } }
如果不想將所有的接口都通過(guò)swagger管理的話,可以將RequestHandlerSelectors.any()
修改為RequestHandlerSelectors.basePackage()
配置靜態(tài)訪問(wèn)資源
@Configuration public class WebMvcConfig implements WebMvcConfigurer { @Override public void addResourceHandlers(ResourceHandlerRegistry registry) { // 解決 swagger-ui.html 404報(bào)錯(cuò) registry.addResourceHandler("/swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/"); } }
到這里為止swagger就已經(jīng)配置完了,可以啟動(dòng)項(xiàng)目,然后訪問(wèn)如下鏈接即可http://localhost:9000/swagger...
端口號(hào)applicationContext中設(shè)置的端口號(hào)。
集成swagger-bootstrap-ui
由于個(gè)人感覺(jué)原生的swagger-ui不太好看,網(wǎng)上提供了swagger-bootstrap-ui。
pom依賴
<dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>swagger-bootstrap-ui</artifactId> <version>1.9.3</version> </dependency>
配置靜態(tài)訪問(wèn)資源
@Configuration public class WebMvcConfig implements WebMvcConfigurer { @Override public void addResourceHandlers(ResourceHandlerRegistry registry) { // 解決 swagger-ui.html 404報(bào)錯(cuò) registry.addResourceHandler("/swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/"); // 解決 doc.html 404 報(bào)錯(cuò) registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/"); } }
這時(shí)只需要訪問(wèn)以下鏈接即可http://localhost:9000/doc.html
swagger常用注解
@Api:用在類上,標(biāo)志此類是Swagger資源
屬性名稱 | 備注 |
---|---|
value | 該參數(shù)沒(méi)什么意義,在UI界面上不顯示,所以不用配置 |
tags | 說(shuō)明該類的作用,參數(shù)是個(gè)數(shù)組,可以填多個(gè) |
description | 對(duì)api資源的描述 |
@ApiOperation:用在方法上,描述方法的作用
屬性名稱 | 備注 |
---|---|
value | 方法的用途和作用 |
tags | 方法的標(biāo)簽,可以設(shè)置多個(gè)值 |
notes | 方法的注意事項(xiàng)和備注 |
response | 返回的類型(盡量不寫(xiě),由swagger掃描生成) |
@ApiImplicitParams:包裝器:包含多個(gè)ApiImplicitParam對(duì)象列表
屬性名稱 | 備注 |
---|---|
value | 多個(gè)ApiImplicitParam配置 |
@ApiParam:用于Controller中方法的參數(shù)說(shuō)明
屬性名稱 | 備注 |
---|---|
name | 屬性名稱 |
value | 屬性值 |
defaultValue | 默認(rèn)屬性值 |
allowableValues | 可以不配置 |
required | 是否屬性必填 |
allowMultiple | 文件上傳時(shí),是否允許多文件上傳 |
@ApiImplicitParam:定義在@ApiImplicitParams注解中,定義單個(gè)參數(shù)詳細(xì)信息,如果只有一個(gè)參數(shù),也可以定義在方法上
屬性名稱 | 備注 |
---|---|
name | 參數(shù)名 |
value | 參數(shù)說(shuō)明 |
dataType | 參數(shù)類型 |
paramType | 表示參數(shù)放在哪里 header : 請(qǐng)求參數(shù)的獲取:@RequestHeader query : 請(qǐng)求參數(shù)的獲?。篅RequestParam path : 請(qǐng)求參數(shù)的獲取:@PathVariable body : 不常用 form : 不常用 |
defaultValue | 參數(shù)的默認(rèn)值 |
required | 參數(shù)是否必須傳 |
@ApiModel:用在類上,表示對(duì)類進(jìn)行說(shuō)明,用于實(shí)體類中的參數(shù)接收說(shuō)明
屬性名稱 | 備注 |
---|---|
value | 默認(rèn)為類的名稱 |
description | 對(duì)該類的描述 |
@ApiModelProperty:在model類的屬性添加屬性說(shuō)明
屬性名稱 | 備注 |
---|---|
value | 屬性描述 |
name | 屬性名稱 |
allowableValues | 參數(shù)允許的值 |
dataType | 數(shù)據(jù)類型 |
required | 是否必填 |
@ApiResponses:包裝器:包含多個(gè)ApiResponse對(duì)象列表
屬性名稱 | 備注 |
---|---|
value | 多個(gè)ApiResponse配置 |
@ApiResponse:定義在@ApiResponses注解中,一般用于描述一個(gè)錯(cuò)誤的響應(yīng)信息
屬性名稱 | 備注 |
---|---|
code | 響應(yīng)碼 |
message | 狀態(tài)碼對(duì)應(yīng)的響應(yīng)信息 |
response | 默認(rèn)響應(yīng)類 Void |
responseContainer | 參考ApiOperation中配置 |
@ApiIgnore():用于類或者方法上,不被顯示在頁(yè)面上
總結(jié)
除上面之外有點(diǎn)值得注意的是,如果是上傳文件的話,需要把@ApiImplicitParam中的dataType屬性配置為_(kāi)_File否則在swagger中會(huì)顯示為文本框而不是上傳按鈕
如果需要項(xiàng)目代碼,可以去我的github中下載;具體代碼可以查看swagger目錄
以上就是本文的全部?jī)?nèi)容,希望對(duì)大家的學(xué)習(xí)有所幫助,也希望大家多多支持億速云。
免責(zé)聲明:本站發(fā)布的內(nèi)容(圖片、視頻和文字)以原創(chuàng)、轉(zhuǎn)載和分享為主,文章觀點(diǎn)不代表本網(wǎng)站立場(chǎng),如果涉及侵權(quán)請(qǐng)聯(lián)系站長(zhǎng)郵箱:is@yisu.com進(jìn)行舉報(bào),并提供相關(guān)證據(jù),一經(jīng)查實(shí),將立刻刪除涉嫌侵權(quán)內(nèi)容。