SpringMVC与Swagger的集成与一些问题的记录

Swagger概述

1. swagger对Spring或者Springboot项目中所暴露的Restful接口，提供自动化网页文档生成插件
2. 可以在swagger中对restful接口进行模拟调用

Swgger的环境的配置

Swagger所需的jar包特别多，一定要通过Maven等jar包管理插件去下载依赖包，不要自己找

前置条件

1. 创建maven项目以便对所需jar包进行统一管理
2. 项目中已经集成Spring以便进行反转控制
3. 在配置web.xml的spring-filtter时，要开放所有过滤后缀请求

<servlet>
	<servlet-name>springmvc</servlet-name>
	<servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
	<!-- 保证SpringMVC能够正确找到Spring配置文件 -->
	<init-param>
		<param-name>contextConfigLocation</param-name>
		<param-value>classpath*:/applicationContext.xml</param-value>
	</init-param>
</servlet>
	
<servlet-mapping>
	<servlet-name>springmvc</servlet-name>
	<!-- 不单是.do请求，而是所有请求 -->
	<url-pattern>/</url-pattern>
</servlet-mapping>

下载依赖包

maven中需要指定的jar包只有如下两个，但mavne会自动下载配套的10多个jar包

注意：

1. 一定是io.springfox组下的swagger包，而不是其他组的swagger
2. 版本不宜过高，2.7或2.8即可，过高版本容易出现一些不可预期的问题

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.7.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.7.0</version>
</dependency>

配置swagger的参数文件

1. 一般可以在项目的任意包下创建一个SwaggerConfing.java(名称自定)文件用于设置Swagger参数
2. 因为配置了Spring/Springboot，因此将该配置类的实例化和调用过程交由Spring进行实现
3. 配置类建议实现WebMvcConfigurerAdapter接口，以便对swagger的jar包中的静态资源文件进行网络请求放行

具体代码如下所示

package com.geoq.framework.swagger;
//以下三个注解都必须加上
@Configuration
@EnableSwagger2
@EnableWebMvc
public class SwaggerConfig extends WebMvcConfigurerAdapter 
{
	 @Bean
	 public Docket api() {
	      return new Docket(DocumentationType.SWAGGER_2)
	                .select()
	                .apis(RequestHandlerSelectors.basePackage("com.geoq"))  //swagger只搜索特定包下的所有Swagger支持的注解
	                //.apis(RequestHandlerSelectors.withClassAnnotation(Api.class))  //只显示添加@Api注解的类
	                .build()
	                .apiInfo(apiInfo());
	 }

	 private ApiInfo apiInfo() {
	       return new ApiInfoBuilder()
	                .title("项目功能开发接口")  //页面住标题
	                .description("HTTP对外开放接口")   //页面描述标题
	                .version("1.0.0")   //api version
	                .build();
	 }
	 
	 //对swagger包中的静态资源进行放行，否则容易出现访问安全异常，或空白页面
	 @Override
	 public void addResourceHandlers(ResourceHandlerRegistry registry) {
	     registry.addResourceHandler("swagger-ui.html")
	       .addResourceLocations("classpath:/META-INF/resources/");
	  
	     registry.addResourceHandler("/webjars/**")
	       .addResourceLocations("classpath:/META-INF/resources/webjars/");
	 }
}

确保Spring工厂可以管理到这个类

以自动扫描为例

<context:component-scan base-package="com.geoq.framework"></context:component-scan>

Swagger的基本注解

基本注解表

标签名	功能说明	作用点
@Api	标识当前类被Swagger扫描管理	Controller类
@ApiOperation()	标识当前方法被Swagger扫描管理	Controller 的方法
@ApiParam	标识当前函数参数被Swagger扫描管理	Controller方法的参数
@ApiModel()	标识当前类是请求/响应数据传输实体	VO类
@ApiModelProperty	标识当前类是请求/响应数据传输实体的属性	VO类属性

使用实例

@RestController /*Spring的注解*/
@RequestMapping("/demo") /*Spring的注解*/
@Api(value = "/ProductController", tags = "接口开放示例") /*Swagger的注解，标识一个API分组*/
public class DemoController
{
	@Autowired
	private DemoService service;
	
	/*Spring的注解*/
	@RequestMapping(value = "/HelloWorld.do", method = RequestMethod.POST)
	/*Swagger的注解，标识一个Restful请求接口*/
	@ApiOperation(value = "网络通讯测试", notes = "网络通讯测试", httpMethod = "POST", response = BaseDataMessage.class)
	public ResponseEntity<BaseDataMessage> HelloWorld(HttpServletRequest request)
	{
		BaseDataMessage dataMessage = new BaseDataMessage();
		int status = service.HelloWorld(request, dataMessage);
		return ResponseEntity.status(status).body(dataMessage);
	}
}

运行结果与问题排错

正常运行

在浏览器地址栏中输入host:port/projectname/swagger-ui.html，即可在页面中弹出如下页面

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-eYqhDxrH-1602291105477)(https://note.youdao.com/yws/api/personal/file/C6B4B34BF68A4E519CB77E09A6F77006?method=download&shareKey=f156b1ebdfb873de0f6d9634cd17cd3b)]

网页自身404

1. Spring集成错误，
2. Spring没有正确扫描到Swagger配置类所在包
3. Swagger配置类的注解不全

网页仅有Swagger工具条，没有Restful接口条目

1. 检查静态资源访问没有被正确放行，检查配置类的addResourceHandlers函数是否已经添加
2. Spring没有开启所有请求后缀的过滤，只放行了.do等特殊请求后缀

安全验证错误

1. Swagger版本过高或者与其他jar包有冲突
2. 不是下载的io.springfox组下的swagger包