swagger的使用及踩坑

swagger的使用有两种方式:

https://blog.csdn.net/weixin_37509652/article/details/80094370

按照该博客中的第一种方式使用@EnableSwagger2Doc注解其实是直接使用的swagger默认配置,生成的页面如下,

手动配置首先要去除启动类上@EnableSwagger2Doc注解,否则会报错. 配置有两种方式,

1.配置类

/**
 * Swagger2API文档的配置
 */
@Configuration
@EnableSwagger2
public class Swagger2Config extends WebMvcConfigurationSupport {
    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .ignoredParameterTypes(Principal.class)
                .select()
                //为当前包下controller生成API文档
                .apis(RequestHandlerSelectors.basePackage("cn.com.controller"))
                //为有@Api注解的Controller生成API文档
//                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                //为有@ApiOperation注解的方法生成API文档
//                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("接口")
                .description("create by lr")
                .contact("lr")
                .version("1.0")
                .build();
    }

    /**
     * 防止@EnableMvc把默认的静态资源路径覆盖了，手动设置的方式
     *
     * @param registry
     */
    @Override
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        // 解决静态资源无法访问
        registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
        // 解决swagger无法访问
        registry.addResourceHandler("/swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        // 解决swagger的js文件无法访问
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

2.配置文件

这种方式好像仅仅适用于swagger-spring-boot-starter的依赖

 

手动配置后的页面如下,

记录使用swagger中的遇到的一个问题:

访问接口页面地址时, 页面正常访问, 但是后端程序报错:

Illegal DefaultValue null for parameter type integer. java.lang.NumberFormatException: For input string: "".

google到一篇文章,里面有解决方案.

https://github.com/swagger-api/swagger-core/issues/2979

根据文章中的描述, 是由于在使用@ApiParam注解并且没有自定义example值时, swagger-models-1.5.20.jar源码获取example发生的转换异常.

随后我做了一段追踪,

从报错信息来看可以定位到AbstractSerializableParameter.getExample()方法

使用@ApiParam注解, 在访问swagger-ui.html时,  获取到example的默认值为空字符串, 在转换时抛出异常.

解决方法:

        <dependency>
			<groupId>com.spring4all</groupId>
			<artifactId>swagger-spring-boot-starter</artifactId>
			<exclusions>
				<exclusion>
					<groupId>io.swagger</groupId>
					<artifactId>swagger-models</artifactId>
				</exclusion>
			</exclusions>
		</dependency>

		<dependency>
			<groupId>io.swagger</groupId>
			<artifactId>swagger-models</artifactId>
			<version>1.5.21</version>
		</dependency>

1.5.21的AbstractSerializableParameter.getExample()方法增加了对空字符串的判断