SpringMVC中使用swagger为api接口生成文档

1.添加swagger的maven依赖

<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-databind</artifactId>
<version>2.6.0</version>
</dependency>
<dependency>
<groupId>com.mangofactory</groupId>
<artifactId>swagger-springmvc</artifactId>
<version>1.0.2</version>
</dependency>

2.编写swagger配置类

package com.zhanjixun.config;

import javax.annotation.Resource;

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
@EnableWebMvc
@EnableSwagger
@ComponentScan(basePackages = { "com.zhanjixun.controller" })
public class SwaggerConfig {
@Resource
private SpringSwaggerConfig springSwaggerConfig;

@Bean
public SwaggerSpringMvcPlugin customImplementation() {
return new SwaggerSpringMvcPlugin(this.springSwaggerConfig).apiInfo(apiInfo()).includePatterns("/(?!error).*");
}

private ApiInfo apiInfo() {

ApiInfo apiInfo = new ApiInfo(
"Swagger-ui演示",//
"使用Swagger产生的API接口文档",//
"<a href='http://blog.csdn.net/zhanjixun'>CSDN</a>",
"zhanjixun@qq.com",//
"API许可证",//
"http://blog.csdn.net/zhanjixun"//
);
return apiInfo;
}
}

3.在spring-mvc.xml中加入swagger的配置类

<bean class="com.zhanjixun.config.SwaggerConfig" />

4.为controller添加接口描述

package com.zhanjixun.controller;

import java.util.HashMap;
import java.util.Map;

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.Api;
import com.wordnik.swagger.annotations.ApiOperation;
import com.wordnik.swagger.annotations.ApiParam;

@Controller
@RequestMapping("/user")
@Api(value = "user", description = "用户相关接口")
public class UserController {

@RequestMapping(value = "/login", method = RequestMethod.POST)
@ResponseBody
@ApiOperation(value = "登录", notes = "用户登录", httpMethod = "POST", response = Object.class)
public Object login(@ApiParam(value = "用户名", required = true) @RequestParam String username) {
Map<String, Object> map = new HashMap<>();
map.put("status", "200");
return map;
}

@RequestMapping(value = "/update", method = RequestMethod.POST)
@ResponseBody
@ApiOperation(value = "更新用户信息", notes = "更新用户信息", httpMethod = "POST", response = Object.class)
public Object update(@ApiParam(value = "用户名", required = true) @RequestParam String username) {
Map<String, Object> map = new HashMap<>();
map.put("status", "200");
return map;
}
}

相关的API：在线文档查看

5.查看生成的文档
到https://github.com/swagger-api/swagger-ui下载swagger-ui
讲dist目录下的所有文件放到自己的web项目中，在浏览器访问 刚刚放好的dist目录下的index.html 
如我将dist目录所有文件放到webContent下的doc文件夹中 就在浏览器中打开http://localhost:8080/swagger-ui/doc/index



注意要修改index.html中的http://petstore.swagger.io/v2/swagger.json为 /swagger-ui/api-docs 其中swagger-ui是web项目名
 其实不修改也可以  打开index.html后在swagger上面右边的地址栏输入http://localhost:8080/swagger-ui/api-docs也可以看到文档 不过这样要每次都输入而已





6.常见的问题

500 Servlet.init()问题 可能是controller添加注解的问题

代码下载：http://download.csdn.net/detail/zhanjixun/9739584