整合swagger2生成Restful Api接口文檔

swagger Restful文檔生成工具 2017-9-30

官方地址：https://swagger.io/docs/specification/about/

官方Github：https://github.com/swagger-api/swagger-core/wiki/Annotations

啟動(dòng)項(xiàng)目，訪問http://localhost:8082/swagger-ui.html查看API

注意，此項(xiàng)目示例中，使用了三種ui依賴，每種依賴對應(yīng)的訪問頁面不同：

springfox-swagger-ui -> http://localhost:8082/swagger-ui.html
swagger-bootstrap-ui -> http://localhost:8082/doc.html
swagger-ui-layer -> http://localhost:8082/docs.html

使用方法：

1.添加依賴（springfox-swagger2依賴是必須的，三種ui依賴只需要使用一個(gè)就行）

<dependency><groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.2.2</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.2.2</version> </dependency>

2.創(chuàng)建配置文件Swagger2Config.java

@EnableSwagger2 @Configuration public class Swagger2Config { @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() //為當(dāng)前包路徑 .apis(RequestHandlerSelectors.basePackage("com.zyd.controller")) .paths(PathSelectors.any()) .build(); } //構(gòu)建 api文檔的詳細(xì)信息函數(shù) private ApiInfo apiInfo() { return new ApiInfoBuilder() //頁面標(biāo)題 .title("Spring Boot 測試使用 Swagger2 構(gòu)建RESTful API") .termsOfServiceUrl("http://localhost/") //創(chuàng)建人 .contact("zhyd") //版本號 .version("1.0") //描述 .description("API 描述") .build(); } }

注：@EnableSwagger2注解一定不要漏掉

3.編寫文檔

@RestController @RequestMapping("/demo") @Api(value = "測試Swagger2",description="簡單的API") public class UserController { @ApiOperation(value = "創(chuàng)建用戶", notes = "根據(jù)User對象創(chuàng)建用戶") @ApiImplicitParams({ @ApiImplicitParam(dataType = "java.lang.Long", name = "id", value = "id", required = true, paramType = "path"), @ApiImplicitParam(dataType = "User", name = "user", value = "用戶信息", required = true) }) @ApiResponses({ @ApiResponse(code = 500, message = "接口異常"), }) @RequestMapping(value = "/user/{id}", method = RequestMethod.POST) public User insert(@PathVariable Long id, @RequestBody User user) { System.out.println("id:" + id + ", user:" + user); user.setId(id); return user; } }

注意：如果api文檔只是針對開發(fā)人員使用的，就需要后臺對v2/api-docs路徑進(jìn)行過濾，對非開發(fā)人員應(yīng)該是不可見的。

自定義api頁面

本例是使用的swagger-ui-layer主題（鏈接請見本文最后）。使用自定義api頁面就不需要在pom中配置ui依賴了，詳情查看static目錄

api頁面訪問地址：http://localhost:8082/api.html

頁面效果參考

swagger-ui.html

bootstrap-ui.html

layer-ui.html.html

layer-ui-custom.html

參考鏈接

swagger-ui-layer地址：https://github.com/caspar-chen/swagger-ui-layer

Swagger-Bootstrap-UI地址：https://github.com/xiaoymin/Swagger-Bootstrap-UI

有問題歡迎留言（可能回復(fù)有延遲，見諒）。

其他

源碼請移步：Github源碼

相關(guān)文章導(dǎo)讀

SpringBoot項(xiàng)目實(shí)戰(zhàn)（8）：四種讀取properties文件的方式

SpringBoot項(xiàng)目實(shí)戰(zhàn)（7）：自定義異常處理界面

SpringBoot項(xiàng)目實(shí)戰(zhàn)（6）：開啟定時(shí)任務(wù)

SpringBoot項(xiàng)目實(shí)戰(zhàn)（5）：集成分頁插件

SpringBoot項(xiàng)目實(shí)戰(zhàn)（4）：集成Mybatis

SpringBoot項(xiàng)目實(shí)戰(zhàn)（3）：整合Freemark模板

SpringBoot項(xiàng)目實(shí)戰(zhàn)（2）：集成SpringBoot

SpringBoot項(xiàng)目實(shí)戰(zhàn)（1）：新建Maven項(xiàng)目

?

https://www.imooc.com/article/20521

?webapi文檔描述-swagger

https://www.codercto.com/a/23839.html

http://blog.didispace.com/spring-boot-starter-swagger-1.2.0/

慕課手記：

http://www.imooc.com/article/15384

?

轉(zhuǎn)載于:https://www.cnblogs.com/gaogaoyanjiu/p/9662018.html

總結(jié)

以上是生活随笔為你收集整理的整合swagger2生成Restful Api接口文档的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯(cuò)，歡迎將生活随笔推薦給好友。