SpringMvc：整合springfox-swagger2生成在线API文档
Springboot 集成swagger2 即springfox-swagger2的方法请参考
Swagger：JAVA 前后端调试利器，接口文档自动生成工具的简单使用示例_奋斗鱼-CSDN博客
下面介绍SpringMVC集成springfox-swagger2的方法(当中遇到的问题和解决方案请看文章末尾)
步骤一：引入依赖包
io.springfox
springfox-swagger2
2.7.0
io.springfox
springfox-swagger-ui
2.7.0
com.github.xiaoymin
swagger-bootstrap-ui
1.9.6
步骤二：添加配置文件
在controller同级目录下新建config文件夹，并创建 SwaggerConfig类。
注意：basePackage需要修改成你的controller路径，若有多个controller层则配置到上一级即可。
如存在com.zhc.a.controller和com.zhc.b.controller两个目录，配置为"com.zhc"
package com.zhcsw.chenfuweb.config;
import com.github.xiaoymin.swaggerbootstrapui.annotations.EnableSwaggerBootstrapUI;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
* @ClassName SwaggerConfig
* @Description TODO
*/
// 启动时加载类
@Configuration
// 启用Swagger API文档
@EnableSwagger2
//动态添加响应类注释字段
@EnableSwaggerBootstrapUI
//@Import(BeanValidatorPluginsConfiguration.class)
public class SwaggerConfig {
@Bean
public Docket buildDocket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(buildApiInf())
.select() .apis(RequestHandlerSelectors.basePackage("com.zhcsw.chenfuweb.controller"))//修改成你的controller路径
.paths(PathSelectors.any())
.build();
}
private ApiInfo buildApiInf(){
return new ApiInfoBuilder()
.title("标题")
.termsOfServiceUrl("http://网址链接")
.description("springmvc swagger2")
.contact(new Contact("quan", "http://*.com", "*@163.com"))
.build();
}
}
步骤三：添加配置文件
在spring.xml配置文件中设置swagger的静态资源目录和访问页面。doc.html是swagger UI的固定首页名称(默认是swagger-ui.html，xiaoymin这个UI版本样式会更好看些，名称是doc.html)
步骤四：预览页面
配置完以上步骤，就可以在浏览器上访问看到预览页面了。地址为http://localhost:端口/项目名/doc.html
步骤五：Controller方法配置
现在看下在我们的Controller方法中如何使用。
/**
* @author Quan
* @后台：技术文档管理
*/
@Api(value = "技术文档管理接口",tags = "技术文档管理",protocols = "http")
@RequestMapping("/mweb/document")
@Controller
public class DocumentController {
protected final static Logger logger = LoggerFactory.getLogger(DocumentController.class);
// 查询技术文档列表
@ApiOperation(value = "缴费记录管理--查询技术文档列表",notes="缴费记录管理--查询技术文档列表")
@DynamicParameters(name ="(document)getList",properties = {
@DynamicParameter(value = "文件名",name = "doc_name_name"),
@DynamicParameter(value = "排序字段",name = "order_by"),
@DynamicParameter(value = "当前页码",name = "pageNo",example = "1"),
@DynamicParameter(value = "页行数",name = "pageSize",example = "10")
})
@RequestMapping(value = "/getList", method = RequestMethod.POST)
@ResponseBody
public ResultMsg list(HttpServletResponse response, @RequestBody HashMap map) {
String estr = "查询技术文档列表(document/getList)===：";
logger.debug(estr + map.toString());
ResultMsg rMsg = new ResultMsg();
try {
logger.debug(rMsg.toString());
} catch (Exception e) {
logger.error(estr + e.toString());
return rMsg;
}
}
} 预览效果
以上配置完成。
遇到的问题
1.提示probably due to a new Java class file version that isn't supported yet
说明不支持你当前spring版本不支持，需要升级到高版本，在pom.xml中调整下，我这边改成5.2.4
UTF-8
5.2.4.RELEASE
2.Cannot find class [org.springframework.web.servlet.mvc.annotation.AnnotationMethodHandlerAdapter
在Spring 3.x版中启动Spring MVC的注解功能，完成请求和注解POJO的映射你可能会用到这个类，但新版中已经过时不用此类可以直接删除。
3.org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerAdapter报错
如果你要处理日期格式时你可以用下面这样
4.提示：swagger2 Unable to infer base url. This is common when using dynamic servlet
这可能是由于你配置了拦截器，可以尝试把拦截器先取消掉，验证下是否可以正常。如果你确定是拦截器引起，把swagger的首页doc.html从拦截器中排除掉即可。
5.首页显示出页面却无任何内容
原因和解决方法同4。
