資訊專欄INFORMATION COLUMN
摘要：今天給你們帶來集成的教程。接口返回結(jié)果不明確。這些痛點在前后端分離的大型項目上顯得尤為煩躁。接口返回結(jié)果非常明確，包括數(shù)據(jù)類型，狀態(tài)碼，錯誤信息等。生成后的文件依賴如下這里使用的是的版本。另外，關注之后在發(fā)送可領取免費學習資料。
微信公眾號：一個優(yōu)秀的廢人前言
如有問題或建議，請后臺留言，我會盡力解決你的問題。
快過年了，不知道你們啥時候放年假，忙不忙。反正我是挺閑的，所以有時間寫 blog。今天給你們帶來 SpringBoot 集成 Swagger2 的教程。
什么是 Swagger2Swagger 是一個規(guī)范和完整的框架，用于生成、描述、調(diào)用和可視化 RESTful 風格的 Web 服務。
為什么使用 Swagger2 ？相信剛開始不熟悉 web 開發(fā)的時候，大家都有手寫 Api 文檔的時候。而手寫 Api 文檔主要有以下幾個痛點：
文檔需要更新的時候，需要再次發(fā)送一份給前端，也就是文檔更新交流不及時。
接口返回結(jié)果不明確。
不能直接在線測試接口，通常需要使用工具，比如 postman。
接口文檔太多，不好管理。
這些痛點在前后端分離的大型項目上顯得尤為煩躁。而 Swagger2 的出現(xiàn)恰好能個解決這些痛點。因為 Swagger2 有以下功能：
文檔自動更新，只要生成 Api 的網(wǎng)址沒變，基本不需要跟前端溝通。
接口返回結(jié)果非常明確，包括數(shù)據(jù)類型，狀態(tài)碼，錯誤信息等。
可以直接在線測試文檔，而且還有實例提供給你。
只需要一次配置便可使用，之后只要會有一份接口文檔，非常易于管理。
集成演示首先新建一個 SpringBoot 項目，還不會的參考我這篇舊文—— 如何使用 IDEA 構(gòu)建 Spring Boot 工程
構(gòu)建時，在選擇依賴那一步勾選 Web、LomBok、JPA 和 Mysql 依賴。其中 Mysql 可以不勾，因為我這里用于操作實際的數(shù)據(jù)庫，所以我勾選了。
生成 SpringBoot 后的 Pom 文件依賴如下：這里使用的是 2.4.0 的 Swagger2 版本。
4.0.0 org.springframework.boot spring-boot-starter-parent 2.1.2.RELEASE com.nasus swagger2 0.0.1-SNAPSHOT swagger2 Demo project for Swagger2 1.8 org.springframework.boot spring-boot-starter-data-jpa org.springframework.boot spring-boot-starter-web mysql mysql-connector-java runtime org.springframework.boot spring-boot-starter-test test io.springfox springfox-swagger2 2.4.0 io.springfox springfox-swagger-ui 2.4.0 org.springframework.boot spring-boot-maven-plugin
第二步，在 SpringBoot 啟動類（Application）的同級目錄新建一個 Swagger 配置類，注意 Swagger2 配置類必須與項目入口類 Application 位于同一級目錄，否則生成 Api 文檔失敗，代碼如下：
package com.nasus; 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.service.Contact; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2; /** * Project Name:swagger2-demo
* Package Name:com.nasus
* Date:2019/1/22 22:52
* Description: TODO: 描述該類的作用
* * @author nasus
* Copyright Notice ========================================================= * This file contains proprietary information of Eastcom Technologies Co. Ltd. * Copying or reproduction without prior written approval is prohibited. * Copyright (c) 2019 ======================================================= */ @Configuration // 啟用 Swagger2 @EnableSwagger2 public class Swagger2 { @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) // 文檔信息對象 .apiInfo(apiInfo()) .select() // 被注解的包路徑 .apis(RequestHandlerSelectors.basePackage("com.nasus.controller")) .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() // 標題 .title("springboot 利用 swagger 構(gòu)建 API 文檔") // Api 文檔描述 .description("簡單優(yōu)雅的 restful 風格，https://blog.csdn.net/turodog/") .termsOfServiceUrl("https://blog.csdn.net/turodog/") // 文檔作者信息 .contact(new Contact("陳志遠", "https://github.com/turoDog", "[email protected]")) // 文檔版本 .version("1.0") .build(); } }
第三步，配置被注解的 Controller 類，編寫各個接口的請求參數(shù)，返回結(jié)果，接口描述等等，代碼如下：
package com.nasus.controller; import com.nasus.entity.Student; import com.nasus.service.StudentService; import io.swagger.annotations.Api; import io.swagger.annotations.ApiImplicitParam; import io.swagger.annotations.ApiImplicitParams; import io.swagger.annotations.ApiOperation; import java.util.List; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.web.bind.annotation.DeleteMapping; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.PathVariable; import org.springframework.web.bind.annotation.PostMapping; import org.springframework.web.bind.annotation.PutMapping; import org.springframework.web.bind.annotation.RequestBody; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RequestMethod; import org.springframework.web.bind.annotation.RestController; import springfox.documentation.annotations.ApiIgnore; /** * Project Name:swagger2-demo
* Package Name:com.nasus.controller
* Date:2019/1/22 22:07
* Description: TODO: 描述該類的作用
* * @author nasus
* Copyright Notice ========================================================= * This file contains proprietary information of Eastcom Technologies Co. Ltd. * Copying or reproduction without prior written approval is prohibited. * Copyright (c) 2019 ======================================================= */ @RestController @RequestMapping("/student") // @Api：修飾整個類，描述Controller的作用 @Api("StudentController Api 接口文檔") public class StudentController { @Autowired private StudentService studentService; // @ApiOperation：描述一個類的一個方法，或者說一個接口 @ApiOperation(value="獲取所有學生列表", notes="獲取所有學生列表") @RequestMapping(value={""}, method= RequestMethod.GET) public ListgetStudent() { List list = studentService.findAll(); return list; } @ApiOperation(value="添加學生信息", notes="添加學生信息") // @ApiImplicitParam：一個請求參數(shù) @ApiImplicitParam(name = "student", value = "學生信息詳細實體", required = true, dataType = "Student") @PostMapping("/save") public Student save(@RequestBody Student student){ return studentService.save(student); } @ApiOperation(value="獲學生信息", notes="根據(jù)url的id來獲取學生詳細信息") @ApiImplicitParam(name = "id", value = "ID", required = true, dataType = "Integer",paramType = "path") @GetMapping("/{id}") public Student findById(@PathVariable("id") Integer id){ return studentService.findById(id); } @ApiOperation(value="刪除學生", notes="根據(jù)url的id來指定刪除的學生") @ApiImplicitParam(name = "id", value = "學生ID", required = true, dataType = "Integer",paramType = "path") @DeleteMapping("/{id}") public String deleteById(@PathVariable("id") Integer id){ studentService.delete(id); return "success"; } @ApiOperation(value="更新學生信息", notes="根據(jù)url的id來指定更新學生信息") // @ApiImplicitParams：多個請求參數(shù) @ApiImplicitParams({ @ApiImplicitParam(name = "id", value = "學生ID", required = true, dataType = "Integer",paramType = "path"), @ApiImplicitParam(name = "student", value = "學生實體student", required = true, dataType = "Student") }) @PutMapping(value="/{id}") public String updateStudent(@PathVariable Integer id, @RequestBody Student student) { Student oldStudent = this.findById(id); oldStudent.setId(student.getId()); oldStudent.setName(student.getName()); oldStudent.setAge(student.getAge()); studentService.save(oldStudent); return "success"; } // 使用該注解忽略這個API @ApiIgnore @RequestMapping(value = "/hi", method = RequestMethod.GET) public String jsonTest() { return " hi you!"; } }
第四步，啟動項目，訪問 http://localhost:8080/swagger-ui.html 地址，結(jié)果如下圖：
項目源代碼github
圖解接口 Swagger2 常用注解簡介@ApiOperation：用在方法上，說明方法的作用 1.value: 表示接口名稱 2.notes: 表示接口詳細描述 @ApiImplicitParams：用在方法上包含一組參數(shù)說明 @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一個請求參數(shù)的各個方面 1.paramType：參數(shù)位置 2.header 對應注解：@RequestHeader 3.query 對應注解：@RequestParam 4.path 對應注解: @PathVariable 5.body 對應注解: @RequestBody 6.name：參數(shù)名 7.dataType：參數(shù)類型 8.required：參數(shù)是否必須傳 9.value：參數(shù)的描述 10.defaultValue：參數(shù)的默認值 @ApiResponses：用于表示一組響應 @ApiResponse：用在@ApiResponses中，一般用于表達一個錯誤的響應信息 1.code：狀態(tài)碼 2.message：返回自定義信息 3.response：拋出異常的類 @ApiIgnore: 表示該接口函數(shù)不對swagger2開放展示 @Api：修飾整個類，描述Controller的作用 @ApiParam：單個參數(shù)描述 @ApiModel：用對象來接收參數(shù) @ApiProperty：用對象接收參數(shù)時，描述對象的一個字段 @ApiIgnore：使用該注解忽略這個API @ApiError ：發(fā)生錯誤返回的信息注意事項
@ApiImplicitParam 注解下的 paramType 屬性,會影響接口的測試,如果設置的屬性跟spring 的注解對應不上,會獲取不到參數(shù),例如 paramType=path ,函數(shù)內(nèi)卻使用@RequestParam 注解,這樣,可能會獲取不到傳遞進來的參數(shù),需要按照上面進行對應,將 @RequestParam 注解改為 @PathVariable 才能獲取到對應的參數(shù)。
后語以上就是我對 Swagger2 的理解與使用，以上只是教大家入門 Swagger2 ，想要深入使用還是希望自行查閱官方文檔。最后，對 Python 、Java 感興趣請長按二維碼關注一波，我會努力帶給你們價值，如果覺得本文對你哪怕有一丁點幫助，請幫忙點好看，讓更多人知道。
另外，關注之后在發(fā)送 1024 可領取免費學習資料。資料內(nèi)容詳情請看這篇舊文：Python、C++、Java、Linux、Go、前端、算法資料分享
文章版權(quán)歸作者所有，未經(jīng)允許請勿轉(zhuǎn)載,若此文章存在違規(guī)行為，您可以聯(lián)系管理員刪除。
轉(zhuǎn)載請注明本文地址：http://systransis.cn/yun/73335.html
摘要：另外很容易構(gòu)建風格的，簡單優(yōu)雅帥氣，正如它的名字。配置一些基本的信息。三寫生產(chǎn)文檔的注解通過注解表明該接口會生成文檔，包括接口名請求方法參數(shù)返回信息的等等。四參考資料中使用構(gòu)建強大的文檔 swagger,中文拽的意思。它是一個功能強大的api框架，它的集成非常簡單，不僅提供了在線文檔的查閱，而且還提供了在線文檔的測試。另外swagger很容易構(gòu)建restful風格的api，簡單優(yōu)雅帥氣...
摘要：再通過函數(shù)創(chuàng)建的之后，用來創(chuàng)建該的基本信息這些基本信息會展現(xiàn)在文檔頁面中。函數(shù)返回一個實例用來控制哪些接口暴露給來展現(xiàn)，本例采用指定掃描的包路徑來定義，會掃描該包下所有定義的，并產(chǎn)生文檔內(nèi)容除了被指定的請求。 showImg(http://download.qfeoo.com/kotlin_springboot_logo.png); 這里有個地方需要注意，在測試WebFlux集成Swa...
摘要：下一代服務端開發(fā)下一代服務端開發(fā)第部門快速開始第章快速開始環(huán)境準備，，快速上手實現(xiàn)一個第章企業(yè)級服務開發(fā)從到語言的缺點發(fā)展歷程的缺點為什么是產(chǎn)生的背景解決了哪些問題為什么是的發(fā)展歷程容器的配置地獄是什么從到下一代企業(yè)級服務開發(fā)在移動開發(fā)領域 《 Kotlin + Spring Boot ： 下一代 Java 服務端開發(fā) 》 Kotlin + Spring Boot ： 下一代 Java...
閱讀 3202·2023-04-26 01:39
閱讀 3354·2023-04-25 18:09
閱讀 1623·2021-10-08 10:05
閱讀 3241·2021-09-22 15:45
閱讀 2790·2019-08-30 15:55
閱讀 2401·2019-08-30 15:54
閱讀 3173·2019-08-30 15:53
閱讀 1335·2019-08-29 12:32
