隨着微服務架構體系的發展和應用, 為了前后端能夠更好的集成與對接,同時為了項目的方便交付,每個項目都需要提供相應的API文檔。
來源:PC端、微信端、H5端、移動端(安卓和IOS端)
傳統的API文檔編寫存在以下幾個痛點:
對API文檔進行更新的時候,需要通知前端開發人員,導致文檔更新交流不及時;
API接口返回信息不明確
大公司中肯定會有專門文檔服務器對接口文檔進行更新。
缺乏在線接口測試,通常需要使用相應的API測試工具,比如postman、SoapUI等
接口文檔太多,不便於管理
為了解決傳統API接口文檔維護的問題,為了方便進行測試后台Restful接口並實現動態的更新,因而引入Swagger接口工具。
Swagger具有以下優點
1.功能豐富:支持多種注解,自動生成接口文檔界面,支持在界面測試API接口功能;
2.及時更新:開發過程中花一點寫注釋的時間,就可以及時的更新API文檔,省心省力;
3.整合簡單:通過添加pom依賴和簡單配置,內嵌於應用中就可同時發布API接口文檔界面,不需要部署獨立服務。
<parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>2.0.1.RELEASE</version> </parent> <!-- 管理依賴 --> <dependencyManagement> <dependencies> <dependency> <groupId>org.springframework.cloud</groupId> <artifactId>spring-cloud-dependencies</artifactId> <version>Finchley.M7</version> <type>pom</type> <scope>import</scope> </dependency> </dependencies> </dependencyManagement> <dependencies> <!-- SpringBoot整合Web組件 --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <!-- SpringBoot整合eureka客戶端 --> <dependency> <groupId>org.springframework.cloud</groupId> <artifactId>spring-cloud-starter-netflix-eureka-client</artifactId> </dependency> <!-- swagger2 一個做ui 一個做提供接口的--> <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> </dependencies> <!-- 注意: 這里必須要添加, 否者各種依賴有問題 --> <repositories> <repository> <id>spring-milestones</id> <name>Spring Milestones</name> <url>https://repo.spring.io/libs-milestone</url> <snapshots> <enabled>false</enabled> </snapshots> </repository> </repositories>
Controller:
package com.toov5.api; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RestController; import io.swagger.annotations.Api; import io.swagger.annotations.ApiOperation; @Api("swaggerdemo控制器") //接口描述 @RestController public class SwaggerController { @ApiOperation(value = "swagger演示接口") //具體描述 @GetMapping("/swaggerIndex") public String swaggerIndex() { return "swaggerIndex"; } }
創建config包,並且貼入依賴:
@Configuration @EnableSwagger2 public class SwaggerConfig { @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select() // api掃包 .apis(RequestHandlerSelectors.basePackage("com.itmayiedu.api")).paths(PathSelectors.any()).build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder().title("Toov5|微服務電商系統").description("demo") .termsOfServiceUrl("http://www.itmayiedu.com") // .contact(contact) .version("1.0").build(); } }
yml:
###服務啟動端口號 server: port: 6060 ###服務名稱 spring: application: name: springboot-swagger
訪問:
傳入參數型的接口:
package com.toov5.api; import org.aspectj.weaver.tools.Trace; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RestController; import io.swagger.annotations.Api; import io.swagger.annotations.ApiImplicitParam; import io.swagger.annotations.ApiOperation; @Api("swaggerdemo控制器") //接口描述 @RestController public class SwaggerController { @ApiOperation(value = "swagger演示接口") //具體描述 @GetMapping("/swaggerIndex") public String swaggerIndex() { return "swaggerIndex"; } @ApiOperation(value = "獲取會員信息接口") //具體描述 @ApiImplicitParam(name="userName",value="用戶信息參數",required=true,dataType="String") //傳入的參數 ,描述 , 必須傳遞true , 類型String @GetMapping("/getMembe") public String getMember(String userName) { System.out.println(userName); return "userName"+userName; } }
點擊try out
然后傳入參數, excute執行一下