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相关的依赖
<!-- swagger API document -->
<dependency>
<groupId>com.mangofactory</groupId>
<artifactId>swagger-springmvc</artifactId>
<version>0.6.5</version>
</dependency>
2.创建classpath路径下创建一个swagger.properties, 添加如下内容：
documentation.services.version=1.0
documentation.services.basePath=http://localhost:8080/yourcontextpath
3.在springMVC的main-servlet.xml文件添加如下配置
<context:property-placeholder location="classpath:swagger.properties" />
<bean id="documentationConfig" class="com.mangofactory.swagger.configuration.DocumentationConfig" />
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<String, String> queryAPIInfo() {
logger.info("查询更新新版本号");
Map<String, String> map = new HashMap<String, String>();
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<String, String> queryData(@RequestParam String words) {
logger.info("查询更新新版本号");
Map<String, String> map = new HashMap<String, String>();
map.put("keyword", words);
map.put("data", "this is demo data");
return map;
}
}
四：运行swagger-ui测试接口
下载swagger-ui的最新版本到本地，改名为swagger-ui，把dist下面的部署到tomcat
或者任何WEB服务器上，启动后访问如下地址: http://localhost:8080/swagger-ui
注意把swagger-ui中的index.html中的http://petstore.swagger.io/v2/swagger.json改为
http://localhost:8080/your-contextpath /api-docs保存，然后在启动WEB服务器，
显示如下：
展开输入参数以后，点击【try it out】即可测试接口，查看返回数据。
注意：加上之后启动报Bean not found mapping之类的错误，请在对应
xml文件中加上如下的配置：
<context:annotation-config /> <mvc:default-servlet-handler />
