Swagger
简要说明
将Swagger和Swagger UI集成到系统中，可以实现接口可视化界面操作。
版本号
- Swagger UI 2.2.10
- 高于该版本，可能会出现“No operations defined in spec”错误
- 下载地址：https://github.com/swagger-api/swagger-ui/tree/v2.2.10
Swagger UI 配置
下载后解压，将dist目录下的文件拷贝到工程中，这里在static目录下新建了一个swagger-2.2.10文件夹。
静态资源映射
这里放置到静态资源加载目录中，在spring配置文件中开发许可路径即可，这里使用的jeesite快速开发平台，已经对static目录做了设置。
1<!-- 静态资源映射 --> 2 <mvc:resources mapping="/static/**" location="/static/" cache-period="31536000"/>
Pom 配置文件
前3个是swagger的必须jar包，后面几个根据你当前框架中是否使用到了再进行补充。
1<!-- Swagger --> 2 <dependency> 3 <groupId>com.mangofactory</groupId> 4 <artifactId>swagger-springmvc</artifactId> 5 <version>1.0.2</version> 6 </dependency> 7 <dependency> 8 <groupId>com.mangofactory</groupId> 9 <artifactId>swagger-models</artifactId> 10 <version>1.0.2</version> 11 </dependency> 12 <dependency> 13 <groupId>com.wordnik</groupId> 14 <artifactId>swagger-annotations</artifactId> 15 <version>1.3.11</version> 16 </dependency> 17 18<dependency> 19<groupId>com.fasterxml.jackson.core</groupId> 20<artifactId>jackson-core</artifactId> 21<version>2.5.4</version> 22</dependency> 23<dependency> 24<groupId>com.fasterxml.jackson.core</groupId> 25<artifactId>jackson-annotations</artifactId> 26<version>2.5.4</version> 27</dependency> 28<dependency> 29<groupId>com.google.guava</groupId> 30<artifactId>guava</artifactId> 31<version>15.0</version> 32</dependency> 33<dependency> 34<groupId>com.fasterxml</groupId> 35<artifactId>classmate</artifactId> 36<version>1.1.0</version> 37</dependency>
Swagger 配置文件
这里需要注意的是，可以通过两种方式进行配置，这里使用的是注解的方式，如果不使用注解的方式配置需要在Spring配置文件中进行声名。
1package com.thinkgem.jeesite.common.config; 2 3import org.springframework.beans.factory.annotation.Autowired; 4import org.springframework.context.annotation.Bean; 5import org.springframework.context.annotation.ComponentScan; 6import org.springframework.context.annotation.Configuration; 7import org.springframework.web.servlet.config.annotation.EnableWebMvc; 8 9import com.mangofactory.swagger.configuration.SpringSwaggerConfig; 10import com.mangofactory.swagger.models.dto.ApiInfo; 11import com.mangofactory.swagger.plugin.EnableSwagger; 12import com.mangofactory.swagger.plugin.SwaggerSpringMvcPlugin; 13 14@Configuration 15@EnableSwagger 16@EnableWebMvc 17@ComponentScan(basePackages ={"com.thinkgem.jeesite.modules.blog.web"}) 18public class SwaggerConfig { 19 20 private SpringSwaggerConfig springSwaggerConfig; 21 22 /** 23 * Required to autowire SpringSwaggerConfig 24 */ 25 @Autowired 26 public void setSpringSwaggerConfig(SpringSwaggerConfig springSwaggerConfig) 27 { 28 this.springSwaggerConfig = springSwaggerConfig; 29 } 30 31 /** 32 * Every SwaggerSpringMvcPlugin bean is picked up by the swagger-mvc 33 * framework - allowing for multiple swagger groups i.e. same code base 34 * multiple swagger resource listings. 35 */ 36 @Bean 37 public SwaggerSpringMvcPlugin customImplementation() 38 { 39 return new SwaggerSpringMvcPlugin(this.springSwaggerConfig) 40 .apiInfo(apiInfo()) 41 .includePatterns(".*") 42 .swaggerGroup("XmPlatform") 43 .apiVersion("1.0.0"); 44 } 45 46 private ApiInfo apiInfo() 47 { 48 ApiInfo apiInfo = new ApiInfo( 49 "springmvc搭建swagger", 50 "spring-API swagger测试", 51 "My Apps API terms of service", 52 "469088624@qq.com", 53 "web app", 54 "My Apps API License URL"); 55 return apiInfo; 56 } 57}
这里值得注意的是，以下代码为自动扫描装载位置，多个包用英文逗号分割。
@ComponentScan(basePackages ={"com.thinkgem.jeesite.modules.blog.web","com.thinkgem.jeesite.modules.blog.sys"})
Swagger UI index.html文件配置
修改Swagger下的index.html文件，这里值得注意的是判断表达式else后的url设置。
-
配置为“项目访问地址”+/api-docs即可
-
这里因为放在static目录下所以采用js表达式处理了一下
<!DOCTYPE html> <html> <head> <meta charset="UTF-8"> <meta http-equiv="x-ua-compatible" content="IE=edge"> <title>Swagger UI</title> <link rel="icon" type="image/png" href="images/favicon-32x32.png" sizes="32x32" /> <link rel="icon" type="image/png" href="images/favicon-16x16.png" sizes="16x16" /> <link href='css/typography.css' media='screen' rel='stylesheet' type='text/css'/> <link href='css/reset.css' media='screen' rel='stylesheet' type='text/css'/> <link href='css/screen.css' media='screen' rel='stylesheet' type='text/css'/> <link href='css/reset.css' media='print' rel='stylesheet' type='text/css'/> <link href='css/print.css' media='print' rel='stylesheet' type='text/css'/> <script src='lib/object-assign-pollyfill.js' type='text/javascript'></script> <script src='lib/jquery-1.8.0.min.js' type='text/javascript'></script> <script src='lib/jquery.slideto.min.js' type='text/javascript'></script> <script src='lib/jquery.wiggle.min.js' type='text/javascript'></script> <script src='lib/jquery.ba-bbq.min.js' type='text/javascript'></script> <script src='lib/handlebars-4.0.5.js' type='text/javascript'></script> <script src='lib/lodash.min.js' type='text/javascript'></script> <script src='lib/backbone-min.js' type='text/javascript'></script> <script src='swagger-ui.js' type='text/javascript'></script> <script src='lib/highlight.9.1.0.pack.js' type='text/javascript'></script> <script src='lib/highlight.9.1.0.pack_extended.js' type='text/javascript'></script> <script src='lib/jsoneditor.min.js' type='text/javascript'></script> <script src='lib/marked.js' type='text/javascript'></script> <script src='lib/swagger-oauth.js' type='text/javascript'></script> <!-- Some basic translations --> <!-- <script src='lang/translator.js' type='text/javascript'></script> --> <!-- <script src='lang/ru.js' type='text/javascript'></script> --> <!-- <script src='lang/en.js' type='text/javascript'></script> --> <script type="text/javascript"> $(function () { var url = window.location.search.match(/url=([^&]+)/); var currentUrl = window.location.href; var prefixUrl = ""; if (currentUrl.indexOf("static") != -1) { prefixUrl = currentUrl.substr(0,currentUrl.indexOf("static")); } if (url && url.length > 1) { url = decodeURIComponent(url[1]); } else { url = prefixUrl + "/api-docs"; } hljs.configure({ highlightSizeThreshold: 5000 }); // Pre load translate... if(window.SwaggerTranslator) { window.SwaggerTranslator.translate(); } window.swaggerUi = new SwaggerUi({ url: url, dom_id: "swagger-ui-container", supportedSubmitMethods: ['get', 'post', 'put', 'delete', 'patch'], onComplete: function(swaggerApi, swaggerUi){ if(typeof initOAuth == "function") { initOAuth({ clientId: "your-client-id", clientSecret: "your-client-secret-if-required", realm: "your-realms", appName: "your-app-name", scopeSeparator: " ", additionalQueryStringParams: {} }); } if(window.SwaggerTranslator) { window.SwaggerTranslator.translate(); } }, onFailure: function(data) { log("Unable to Load SwaggerUI"); }, docExpansion: "none", jsonEditor: false, defaultModelRendering: 'schema', showRequestHeaders: false, showOperationIds: false }); window.swaggerUi.load(); function log() { if ('console' in window) { console.log.apply(console, arguments); } } }); </script> </head> <body class="swagger-section"> <div id='header'> <div class="swagger-ui-wrap"> <a id="logo" href="http://swagger.io"><img class="logo__img" alt="swagger" height="30" width="30" src="images/logo_small.png" /><span class="logo__title">swagger</span></a> <form id='api_selector'> <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>
测试访问
输入：http://localhost:18080/jeesite/static/swagger-2.2.10/index.html
对应：http://localhost:18080/jeesite/api-docs
或者：http://192.168.1.222:18080/jeesite/static/swagger-2.2.10/index.html
对应：http://192.168.1.222:18080/jeesite/api-docs
均可访问成功，但需要注意的是index.html中设置的url前缀必须于访问地址前缀一致。
