springboot利用swagger構建api文檔
阿新 • • 發佈：2018-02-13
src spi service iop notes contact span 簡單 quest 
一、引入jar
pom.xml
<!-- swagger -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.6.1</version>
</dependency>
二、配置
package com.lyon.swagger; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.web.context.request.async.DeferredResult; import static com.google.common.base.Predicates.or; import springfox.documentation.builders.ApiInfoBuilder;View Codeimport 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 static springfox.documentation.builders.PathSelectors.regex; @Configuration public class Swagger { @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com.lyon.swagger.controller")) .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("springboot利用swagger構建api文檔") .description("描述:簡單優雅的restfun風格") .termsOfServiceUrl("http://www.lyon.com") //.contact(new Contact("kebi", "tt", "[email protected]"))//作者 .version("1.0") .build(); } @SuppressWarnings("unchecked") @Bean public Docket commonApi() { return new Docket(DocumentationType.SWAGGER_2) .groupName("common") .genericModelSubstitutes(DeferredResult.class) // .genericModelSubstitutes(ResponseEntity.class) .useDefaultResponseMessages(false) .forCodeGeneration(true) .pathMapping("/")// base，最終調用接口後會和paths拼接在一起 .select() .paths(or(regex("/common/.*")))//過濾的接口 .build() .apiInfo(commonApiInfo()); } private ApiInfo commonApiInfo() { return new ApiInfoBuilder() .title("common頁面API")//大標題 .description("springboot平臺的REST API")//詳細描述 .version("1.0")//版本 .contact(new Contact("lyon", "", ""))//作者 .build(); }
配置了分組
默認
@Bean
public Docket createRestApi()
添加了分組
@Bean
public Docket commonApi()
分組註意過濾接口地址
.paths(or(regex("/common/.*"))) //過濾的接口
三、Controller
/** * 根據ID查詢用戶 * @param id * @return */ @ApiOperation(value="獲取用戶詳細信息", notes="根據url的id來獲取用戶詳細信息") @ApiImplicitParam(name = "id", value = "用戶ID", dataType = "Integer", paramType = "path") @RequestMapping(value = "user/{id}", method = RequestMethod.GET) @ResponseBody public User getUserById (@PathVariable(value = "id") Integer id){ System.out.println("id = " + id); User user = null; if(id == 1){ user = new User(1, "科比"); } else { user = new User(id, "我是科比粉絲"); } return user; }
測試結果
分組common
@Controller @RequestMapping("common") public class CommonController { @ApiOperation(value="獲取部門詳細信息", notes="根據url的id來獲取部門詳細信息") //@ApiImplicitParam(name = "id", value = "用戶ID", required = true, dataType = "Integer", paramType = "path") @RequestMapping(value = "dept/{id}", method = RequestMethod.GET) @ResponseBody public Dept getDeptById (@PathVariable(value = "id") Integer id){ System.out.println("id = " + id); Dept dept = null; if(id == 1){ dept = new Dept(1, "綜合部"); } else { dept = new Dept(id, "其他部門"); } return dept; }
四、漢化操作
上面之所以顯示中文是實現了漢化
1.在resourece目錄下創建\META-INF\resoures目錄，然後創建一個名稱為"swagger-ui.html" 的HTML文件。
2.html內容
<!DOCTYPE html> <html> <head> <meta charset="UTF-8"> <title>Swagger UI</title> <link rel="icon" type="image/png" href="webjars/springfox-swagger-ui/images/favicon-32x32.png" sizes="32x32"/> <link rel="icon" type="image/png" href="webjars/springfox-swagger-ui/images/favicon-16x16.png" sizes="16x16"/> <link href=‘webjars/springfox-swagger-ui/css/typography.css‘ media=‘screen‘ rel=‘stylesheet‘ type=‘text/css‘/> <link href=‘webjars/springfox-swagger-ui/css/reset.css‘ media=‘screen‘ rel=‘stylesheet‘ type=‘text/css‘/> <link href=‘webjars/springfox-swagger-ui/css/screen.css‘ media=‘screen‘ rel=‘stylesheet‘ type=‘text/css‘/> <link href=‘webjars/springfox-swagger-ui/css/reset.css‘ media=‘print‘ rel=‘stylesheet‘ type=‘text/css‘/> <link href=‘webjars/springfox-swagger-ui/css/print.css‘ media=‘print‘ rel=‘stylesheet‘ type=‘text/css‘/> <script src=‘webjars/springfox-swagger-ui/lib/object-assign-pollyfill.js‘ type=‘text/javascript‘></script> <script src=‘webjars/springfox-swagger-ui/lib/jquery-1.8.0.min.js‘ type=‘text/javascript‘></script> <script src=‘webjars/springfox-swagger-ui/lib/jquery.slideto.min.js‘ type=‘text/javascript‘></script> <script src=‘webjars/springfox-swagger-ui/lib/jquery.wiggle.min.js‘ type=‘text/javascript‘></script> <script src=‘webjars/springfox-swagger-ui/lib/jquery.ba-bbq.min.js‘ type=‘text/javascript‘></script> <script src=‘webjars/springfox-swagger-ui/lib/handlebars-4.0.5.js‘ type=‘text/javascript‘></script> <script src=‘webjars/springfox-swagger-ui/lib/lodash.min.js‘ type=‘text/javascript‘></script> <script src=‘webjars/springfox-swagger-ui/lib/backbone-min.js‘ type=‘text/javascript‘></script> <script src=‘webjars/springfox-swagger-ui/swagger-ui.min.js‘ type=‘text/javascript‘></script> <script src=‘webjars/springfox-swagger-ui/lib/highlight.9.1.0.pack.js‘ type=‘text/javascript‘></script> <script src=‘webjars/springfox-swagger-ui/lib/highlight.9.1.0.pack_extended.js‘ type=‘text/javascript‘></script> <script src=‘webjars/springfox-swagger-ui/lib/jsoneditor.min.js‘ type=‘text/javascript‘></script> <script src=‘webjars/springfox-swagger-ui/lib/marked.js‘ type=‘text/javascript‘></script> <script src=‘webjars/springfox-swagger-ui/lib/swagger-oauth.js‘ type=‘text/javascript‘></script> <script src=‘webjars/springfox-swagger-ui/springfox.js‘ type=‘text/javascript‘></script> <!--國際化操作：選擇中文版 --> <script src=‘webjars/springfox-swagger-ui/lang/translator.js‘ type=‘text/javascript‘></script> <script src=‘webjars/springfox-swagger-ui/lang/zh-cn.js‘ type=‘text/javascript‘></script> </head> <body class="swagger-section"> <div id=‘header‘> <div class="swagger-ui-wrap"> <a id="logo" href="http://swagger.io"><span class="logo__title">swagger</span></a> <form id=‘api_selector‘> <div class=‘input‘> <select id="select_baseUrl" name="select_baseUrl"></select> </div> <div class=‘input‘><input placeholder="http://example.com/api" id="input_baseUrl" name="baseUrl" type="text"/></div> <div id=‘auth_container‘></div> <div class=‘input‘><a id="explore" class="header__btn" href="#" data-sw-translate>Explore</a></div> </form> </div> </div> <div id="message-bar" class="swagger-ui-wrap" data-sw-translate> </div> <div id="swagger-ui-container" class="swagger-ui-wrap"></div> </body> </html>View Code
參考了：
漢化：https://www.jianshu.com/p/7e543f0f0bd8
分組：http://blog.csdn.net/stonexmx/article/details/77604571
springboot利用swagger構建api文檔