一 ：添加依赖
<!-- swagger-springmvc --> <dependency> <groupId>com.mangofactory</groupId> <artifactId>swagger-springmvc</artifactId> <version>1.0.2</version> </dependency> <dependency> <groupId>com.mangofactory</groupId> <artifactId>swagger-models</artifactId> <version>1.0.2</version> </dependency> <dependency> <groupId>com.wordnik</groupId> <artifactId>swagger-annotations</artifactId> <version>1.3.11</version> </dependency> <!-- swagger-springmvc dependencies --> <dependency> <groupId>com.google.guava</groupId> <artifactId>guava</artifactId> <version>15.0</version> </dependency> <dependency> <groupId>com.fasterxml.jackson.core</groupId> <artifactId>jackson-annotations</artifactId> <version>2.4.4</version> </dependency> <dependency> <groupId>com.fasterxml.jackson.core</groupId> <artifactId>jackson-databind</artifactId> <version>2.4.4</version> </dependency> <dependency> <groupId>com.fasterxml.jackson.core</groupId> <artifactId>jackson-core</artifactId> <version>2.4.4</version> </dependency> <dependency> <groupId>com.fasterxml</groupId> <artifactId>classmate</artifactId> <version>1.1.0</version> </dependency>
二 编写配置类
package s.s.m.swagger; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.ComponentScan; import org.springframework.context.annotation.Configuration; import org.springframework.web.servlet.config.annotation.EnableWebMvc; import com.mangofactory.swagger.configuration.SpringSwaggerConfig; import com.mangofactory.swagger.models.dto.ApiInfo; import com.mangofactory.swagger.plugin.EnableSwagger; import com.mangofactory.swagger.plugin.SwaggerSpringMvcPlugin; @Configuration @EnableSwagger @EnableWebMvc @ComponentScan(basePackages="s.s.m.controller") //添加这个注释，会自动扫描该类中的每一个方法自动生成api文档 public class SwaggerConfig { private SpringSwaggerConfig springSwaggerConfig; /** * Required to autowire SpringSwaggerConfig */ @Autowired public void setSpringSwaggerConfig(SpringSwaggerConfig springSwaggerConfig) { this.springSwaggerConfig = springSwaggerConfig; } /** * Every SwaggerSpringMvcPlugin bean is picked up by the swagger-mvc * framework - allowing for multiple swagger groups i.e. same code base * multiple swagger resource listings. */ @Bean public SwaggerSpringMvcPlugin customImplementation() { return new SwaggerSpringMvcPlugin(this.springSwaggerConfig).apiInfo( apiInfo()).includePatterns(".*?"); } private ApiInfo apiInfo() { ApiInfo apiInfo = new ApiInfo("这是一个测试的应用", //应用名称 "内部人员开发文档", //文档名称 "本API是为了解决学习研究的问题", //概述 "测试开发组", //联系作者 "Licence 2017", //许可证明 "localhost" //url ); return apiInfo; } } 三 spring配置文件添加2个bean
<!-- swagger --> <bean class="com.mangofactory.swagger.configuration.SpringSwaggerConfig" /> <bean class="s.s.m.swagger.SwaggerConfig" />
四 Controller里添加注解
package s.s.m.controller; import java.io.UnsupportedEncodingException; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.stereotype.Controller; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RequestMethod; import org.springframework.web.bind.annotation.RequestParam; import org.springframework.web.bind.annotation.ResponseBody; import s.s.m.service.GoodsService; import com.wordnik.swagger.annotations.Api; import com.wordnik.swagger.annotations.ApiOperation; import com.wordnik.swagger.annotations.ApiParam; @Controller @RequestMapping({"/goods"}) @Api(description="商品服务", value = "GoodsController") public class GoodsController { @Autowired private GoodsService goodsService; @ApiOperation(value = "查询商品", notes = "查询全部商品") @RequestMapping(value = {"/select"}, method = {RequestMethod.GET}) @ResponseBody public String query(){ return goodsService.query(); } @ApiOperation(value = "创建商品",notes = "创建商品") @RequestMapping(value = {"/save"}, method = {RequestMethod.GET}) @ResponseBody public int save(@ApiParam("商品名称") @RequestParam(value="goodsName",required=true) String goodsName) throws UnsupportedEncodingException{ goodsName = new String(goodsName.getBytes("ISO8859-1"),"utf-8"); return goodsService.save(goodsName); } @ApiOperation(value = "查询缓存",notes = "根据key查询缓存") @RequestMapping(value = {"/queryCache"}, method = {RequestMethod.GET}) @ResponseBody public String queryCache(@ApiParam("key") @RequestParam(value="key",required=true) String key){ return goodsService.queryRedis(key); } } 五 配置swagger-ui
index.jsp
<%@ page contentType="text/html;charset=UTF-8" language="java" %> <% String path = request.getContextPath(); String basePath = request.getScheme()+"://"+request.getServerName()+":"+request.getServerPort()+path+""; %> <!DOCTYPE html> <html> <head> <title>AUTH-APIDOCS</title> <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/screen.css' media='print' rel='stylesheet' type='text/css'/> <script type="text/javascript" src="lib/shred.bundle.js"></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-2.0.0.js' type='text/javascript'></script> <script src='lib/underscore-min.js' type='text/javascript'></script> <script src='lib/backbone-min.js' type='text/javascript'></script> <script src='lib/swagger-client.js' type='text/javascript'></script> <script src='swagger-ui.js' type='text/javascript'></script> <script src='lib/highlight.7.3.pack.js' type='text/javascript'></script> <script src='lib/marked.js' type='text/javascript'></script> <!-- enabling this will enable oauth2 implicit scope support --> <script src='lib/swagger-oauth.js' type='text/javascript'></script> <script type="text/javascript"> $(function () { var url = window.location.search.match(/url=([^&]+)/); if (url && url.length > 1) { url = decodeURIComponent(url[1]); } else { url = "<%=basePath%>/api-docs"; } window.swaggerUi = new SwaggerUi({ url: url, dom_id: "swagger-ui-container", supportedSubmitMethods: ['get', 'post', 'put', 'delete'], onComplete: function(swaggerApi, swaggerUi){ if(typeof initOAuth == "function") { /* initOAuth({ clientId: "your-client-id", realm: "your-realms", appName: "your-app-name" }); */ } $('pre code').each(function(i, e) { hljs.highlightBlock(e) }); }, onFailure: function(data) { log("Unable to Load SwaggerUI"); }, docExpansion: "none", sorter : "alpha" }); function addApiKeyAuthorization() { var key = $('#input_apiKey')[0].value; log("key: " + key); if(key && key.trim() != "") { log("added key " + key); window.authorizations.add("api_key", new ApiKeyAuthorization("api_key", key, "query")); } } $('#input_apiKey').change(function() { addApiKeyAuthorization(); }); // if you have an apiKey you would like to pre-populate on the page for demonstration purposes... /* var apiKey = "myApiKeyXXXX123456789"; $('#input_apiKey').val(apiKey); addApiKeyAuthorization(); */ window.swaggerUi.load(); }); </script> </head> <body class="swagger-section"> <div id='header'> <div class="swagger-ui-wrap"> <a id="logo" href="<%=basePath%>/index.jsp">swagger</a> <form id='api_selector'> <div class='input'><input placeholder="http://example.com/api" id="input_baseUrl" name="baseUrl" type="text"/></div> <div class='input'><input placeholder="api_key" id="input_apiKey" name="apiKey" type="text"/></div> <div class='input'><a id="explore" href="#">Explore</a></div> </form> </div> </div> <div id="message-bar" class="swagger-ui-wrap"> </div> <div id="swagger-ui-container" class="swagger-ui-wrap"></div> </body> </html> 六 修改web.xml index.jsp使用的资源要使用默认servlet,如一下文件，如果还有404错误，继续添加对应文件使用默认servlet，不要被springmvc拦截
<servlet-mapping><servlet-name>default</servlet-name><url-pattern>*.jpg</url-pattern></servlet-mapping><servlet-mapping><servlet-name>default</servlet-name><url-pattern>*.png</url-pattern></servlet-mapping><servlet-mapping><servlet-name>default</servlet-name><url-pattern>*.gif</url-pattern></servlet-mapping><servlet-mapping><servlet-name>default</servlet-name><url-pattern>*.ico</url-pattern></servlet-mapping><servlet-mapping><servlet-name>default</servlet-name><url-pattern>*.js</url-pattern></servlet-mapping><servlet-mapping><servlet-name>default</servlet-name><url-pattern>*.css</url-pattern></servlet-mapping><servlet-mapping><servlet-name>default</servlet-name><url-pattern>*.html</url-pattern></servlet-mapping><servlet-mapping><servlet-name>default</servlet-name><url-pattern>*.woff2</url-pattern></servlet-mapping>
