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

本是古典何须时尚 2022-07-11 05:33 252阅读 0赞

**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的配置类**

**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：[在线文档查看][Link 1]

**5.查看生成的文档**

到[https://github.com/swagger-api/swagger-ui][https_github.com_swagger-api_swagger-ui]下载swagger-ui 讲dist目录下的所有文件放到自己的web项目中，在浏览器访问 刚刚放好的dist目录下的index.html

如我将dist目录所有文件放到webContent下的doc文件夹中 就在浏览器中打开http://localhost:8080/swagger-ui/doc/index

![20170117123133687][]

注意要修改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也可以看到文档 不过这样要每次都输入而已

![20170117123729681][]![20170117123734887][]

**6.常见的问题**

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

代码下载：[http://download.csdn.net/detail/zhanjixun/9739584][http_download.csdn.net_detail_zhanjixun_9739584]

[Link 1]: http://www.boyunjian.com/javadoc/org.apache.servicemix.bundles/org.apache.servicemix.bundles.swagger-annotations/1.3.2_1/_/com/wordnik/swagger/annotations/Api.html
[https_github.com_swagger-api_swagger-ui]: https://github.com/swagger-api/swagger-ui
[20170117123133687]: /images/20220711/6913023081704923a2d8d9682bfe1cdc.png
[20170117123729681]: https://img-blog.csdn.net/20170117123729681
[20170117123734887]: /images/20220711/103cc3bc3f714d80bebbd94e9690ecbb.png
[http_download.csdn.net_detail_zhanjixun_9739584]: http://download.csdn.net/detail/zhanjixun/9739584