Spring3 MVC中使用Swagger生成API文档

一：Swagger介绍

Swagger是当前最好用的Restful API文档生成的开源项目，通过swagger-spring项目

实现了与SpingMVC框架的无缝集成功能，方便生成spring restful风格的接口文档，

同时swagger-ui还可以测试spring restful风格的接口功能。其官方网站为：

二：Swagger集成Spring3 MVC步骤

Swagger集成springMVC步骤大致只有如下几步：

1.在pom.xml文件中添加swagger相关的依赖

    		
    			
     
      com.mangofactory
     			
     
      swagger-springmvc
     			
     
      0.6.5
     		
    

2.创建classpath路径下创建一个swagger.properties, 添加如下内容：

documentation.services.version=1.0

documentation.services.basePath=http://localhost:8080/yourcontextpath

3.在springMVC的main-servlet.xml文件添加如下配置

4.重新打包部署你的项目到WEB服务器，访问地址

http://localhost:8080/your-contextpath /api-docs即可看到注解生成的API说明

三：常见swagger注解一览与使用

APIs.@Api

@ApiClass

@ApiError

@ApiErrors

@ApiOperation

@ApiParam

@ApiParamImplicit

@ApiParamsImplicit

@ApiProperty

@ApiResponse

@ApiResponses

@ApiModel

在代码中使用例子：

import java.util.HashMap;import java.util.Map;import org.slf4j.Logger;import org.slf4j.LoggerFactory;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 com.wordnik.swagger.annotations.ApiOperation;@Controller@RequestMapping("/api/swagger")public class SwaggerDemoController {	private static final Logger logger = LoggerFactory.getLogger(SwaggerDemoController.class);		@ApiOperation(value = "query api basic information")	@RequestMapping(value = "/info", method = RequestMethod.GET)	@ResponseBody	public Map
    
      queryAPIInfo() {		logger.info("查询更新新版本号");		Map
     
       map = new HashMap
      
       ();		map.put("language", "Java");		map.put("format", "JSON");		map.put("tools", "swagger");		map.put("version", "1.0");		return map;	}		@ApiOperation(value = "query data with parameters")	@RequestMapping(value = "/data", method = RequestMethod.GET)	@ResponseBody	public Map
       
         queryData(@RequestParam String words) {		logger.info("查询更新新版本号");		Map
        
          map = new HashMap
         
          (); map.put("keyword", words); map.put("data", "this is demo data"); return map; }}
         
        
       
      
     
    

四：运行swagger-ui测试接口

下载swagger-ui的最新版本到本地，改名为swagger-ui，把dist下面的部署到tomcat

或者任何WEB服务器上，启动后访问如下地址:

注意把swagger-ui中的index.html中的改为

http://localhost:8080/your-contextpath /api-docs保存，然后在启动WEB服务器，

显示如下：

展开输入参数以后，点击【try it out】即可测试接口，查看返回数据。

注意：加上之后启动报Bean not found mapping之类的错误，请在对应

xml文件中加上如下的配置：