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 />
