介紹: Swagger是全球最大的OpenAPI規範(OAS)API開發工具框架,支持從設計和文檔到測試和部署的整個API生命周期的開發。(摘自Swagger官網)Swagger說白了就是幫助開發者省去了維護介面文檔的時間,用來調試介面非常方便。 一、創建項目 在上一篇博客中介紹了怎麼創建sprin ...
介紹:
Swagger是全球最大的OpenAPI規範(OAS)API開發工具框架,支持從設計和文檔到測試和部署的整個API生命周期的開發。(摘自Swagger官網)Swagger說白了就是幫助開發者省去了維護介面文檔的時間,用來調試介面非常方便。
一、創建項目
在上一篇博客中介紹了怎麼創建springboot項目,在這篇博客中就不過多講,在博客的最後我會上傳項目的源碼,愛學習的小伙伴們可以下載交流,有問題的小伙伴可以在博客下方留言,博主看到後第一時間會給你回覆。
二、引入swagger2依賴
<!--swagger2--> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.6.1</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.6.1</version> </dependency>
三、創建Swagger2配置類
package com.chaoqi.springboot_swagger.dao.utils; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import springfox.documentation.builders.ApiInfoBuilder; import springfox.documentation.builders.PathSelectors; import springfox.documentation.builders.RequestHandlerSelectors; import springfox.documentation.service.ApiInfo; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2; //讓Spring來載入該類配置 @Configuration //開啟Swagger2 @EnableSwagger2 public class Swagger2 { @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .groupName("HelloWorld") .apiInfo(apiInfo()) .select() // 掃描的包所在位置 .apis(RequestHandlerSelectors.basePackage("com.chaoqi.springboot_swagger.web")) // 掃描的 URL 規則 .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { // 聯繫信息 return new ApiInfoBuilder() // 大標題 .title("") // 描述 .description("") // 服務條款 URL .termsOfServiceUrl("") // 版本 .version("") .build(); } }
創建controller
Swagger2註解說明:
@Api:用在請求的類上,表示對類的說明
tags="說明該類的作用,可以在UI界面上看到的註解"
value="該參數沒什麼意義,在UI界面上也看到,所以不需要配置"
@ApiOperation:用在請求的方法上,說明方法的用途、作用
value="說明方法的用途、作用"
notes="方法的備註說明"
@ApiImplicitParams:用在請求的方法上,表示一組參數說明
@ApiImplicitParam:用在@ApiImplicitParams註解中,指定一個請求參數的各個方面
name:參數名
value:參數的漢字說明、解釋
required:參數是否必須傳
paramType:參數放在哪個地方
· header --> 請求參數的獲取:@RequestHeader
· query --> 請求參數的獲取:@RequestParam
· path(用於restful介面)--> 請求參數的獲取:@PathVariable
· body(不常用)
· form(不常用)
dataType:參數類型,預設String,其它值dataType="Integer"
defaultValue:參數的預設值
@ApiResponses:用在請求的方法上,表示一組響應
@ApiResponse:用在@ApiResponses中,一般用於表達一個錯誤的響應信息
code:數字,例如400
message:信息,例如"請求參數沒填好"
response:拋出異常的類
@ApiModel:用於響應類上,表示一個返迴響應數據的信息
(這種一般用在post創建的時候,使用@RequestBody這樣的場景,
請求參數無法使用@ApiImplicitParam註解進行描述的時候)
@ApiModelProperty:用在屬性上,描述響應類的屬性
package com.chaoqi.springboot_swagger.web; import com.chaoqi.springboot_swagger.dao.domain.MusicInfo; import com.chaoqi.springboot_swagger.service.MusicInfoService; import io.swagger.annotations.Api; import io.swagger.annotations.ApiImplicitParam; import io.swagger.annotations.ApiImplicitParams; import io.swagger.annotations.ApiOperation; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.web.bind.annotation.*; import java.util.List; @RestController @RequestMapping(value = "/music") @Api(tags = "音樂信息") public class MusicInfoController { @Autowired private MusicInfoService musicInfoService; @ApiOperation(value = "根據Id獲取歌手信息") @ApiImplicitParams({ @ApiImplicitParam(name = "id", value = "用戶ID", required = true, paramType = "query", dataType = "Long"), }) @RequestMapping(value = "/showMusic", method = RequestMethod.GET) public List<MusicInfo> getMusicInfo(@RequestParam(name = "id", required = false) Long id) { List<MusicInfo> musicInfo1 = musicInfoService.getMusicInfo(id); return musicInfo1; } @ApiOperation(value="根據Id刪除歌手信息") @ApiImplicitParam(name = "id", value = "用戶ID", required = true, paramType = "query", dataType = "Long") @RequestMapping(value="/deleteMusic", method=RequestMethod.DELETE) public Long deleteUser(@RequestParam(name = "id", required = false) Long id) { Long sum = musicInfoService.getDeleteId(id); return sum; } }
啟動項目運行http://localhost:8080/swagger-ui.html
整合成功,源碼下載地址:https://github.com/caicahoqi/ChaoqiIsPrivateLibrary