1、Swagger2的功能
Swagger2是一個可以生成項目文檔的工具,用來對項目的接口進行描述.是需要簡單的配置就可以立馬使用,並且還可以在自帶的前端界面進行函數的測試.
最核心的作用：編寫和維護接口文檔。
2、spring boot 集成Swgger2
(1)引入相關的依賴：
<!-- swagger --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency> <!--引入ui包--> <dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>swagger-bootstrap-ui</artifactId> <version>1.9.3</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-bean-validators</artifactId> <version>2.9.2</version> </dependency> <!--增加兩個配置解決NumberFormatException--> <dependency> <groupId>io.swagger</groupId> <artifactId>swagger-models</artifactId> <version>1.5.22</version> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-configuration-processor</artifactId> </dependency>
(2)啟動類添加@EnableSwagger2注解
package com.ttbank.flep.file; import org.mybatis.spring.annotation.MapperScan; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; import org.springframework.cloud.client.discovery.EnableDiscoveryClient; import org.springframework.cloud.openfeign.EnableFeignClients; import org.springframework.scheduling.annotation.EnableAsync; import springfox.documentation.swagger2.annotations.EnableSwagger2; @SpringBootApplication(scanBasePackages="com.ttbank") @EnableFeignClients @EnableDiscoveryClient @EnableSwagger2 @EnableAsync @MapperScan("com.ttbank.flep.file.mapper") public class FileApplication { public static void main(String[] args) { SpringApplication.run(FileApplication.class,args); } }
(3)編寫配置類：
package com.ttbank.flep.file.config; import io.swagger.annotations.ApiOperation; 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; @Configuration public class SwaggerConfig { @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() // api掃包 .apis(RequestHandlerSelectors.basePackage("com.ttbank.flep.file.controller")) .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)) .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(); } }
(4)訪問查看
特別注意：根據application.yml的相關配置，訪問對應的網址。
server.servlet.context-path為路徑前綴，若yml中有相關設置，必須在url路徑中添加前綴。
本案例訪問原生swagger2-ui的網址：http://localhost:7003/flep/file/swagger-ui.html
swagger-bootstrap-ui是基於swagger接口api實現的一套UI,因swagger原生ui是上下結構的，在瀏覽接口時不是很清晰,所以，swagger-bootstrap-ui是基於左右菜單風格的方式,適用與我們在開發后台系統左右結構這種風格類似,方便與接口瀏覽。
重點推薦swagger-bootstrap-ui的訪問方式：
http://127.0.0.1:7003/flep/file/doc.html
#application.yml為基本配置文件 server: port: 7003 servlet: context-path: /flep/file #
swagger-ui效果圖為：
swagger-bootstrap-ui效果圖：
3.Swagger2 具體使用案例
首先，介紹Swagger常用注解
@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：用在屬性上，描述響應類的屬性
@ApiParam是一個描述方法參數的注解
注解內的常用屬性有
name：參數名（與請求參數參數名一致）
value：參數說明
required：是否必須
@ApiParam和@ApiImplicitParam類似，都是對方法參數進行標注，但是注解添加的位置不同，@ApiParam添加在方法參數前，@ApiImplicitParam添加在方法前，@ApiImplicitParam擁有dataType和paramType
案例代碼如下：
package com.ttbank.flep.file.controller; import com.ttbank.flep.file.entity.User; import io.swagger.annotations.Api; import io.swagger.annotations.ApiImplicitParam; import io.swagger.annotations.ApiOperation; import org.springframework.web.bind.annotation.*; import java.util.ArrayList; import java.util.List; @Api("用戶信息管理") @RestController @RequestMapping("/user/*") public class UserController { private final static List<User> userList = new ArrayList<>(); { userList.add(new User(1, "Tom", "A fool cat")); userList.add(new User(2, "Jerry", "A clever mouse")); } @ApiOperation("獲取用戶列表") @GetMapping("list") public List userList() { return userList; } @ApiOperation("新增用戶") @PostMapping("add") public boolean add(User user) { return userList.add(user); } @ApiOperation("更新用戶") @ApiImplicitParam(name = "user", value = "單個用戶信息", dataType = "User") @PutMapping("update") public boolean update(User user) { return userList.remove(user) && userList.add(user); } @ApiOperation("批量刪除用戶") @ApiImplicitParam(name = "users", value = "N個用戶信息", dataType = "List<User>") @DeleteMapping("delete") public boolean delete(@RequestBody List<User> users) { return userList.removeAll(users); } }
通過訪問http://127.0.0.1:7003/flep/file/doc.html
參考文獻：https://blog.csdn.net/qq_41291945/article/details/104544417
https://www.cnblogs.com/toov5/p/9974147.html
https://www.cnblogs.com/Shadowplay/p/10606945.html