新手入门教你轻松为springboot项目搭建swagger2

最新推荐文章于 2023-04-17 10:22:57 发布

置顶尖耳朵的阿凡达妹妹

最新推荐文章于 2023-04-17 10:22:57 发布

阅读量367

点赞数 1

分类专栏： swagger2.9.2 文章标签： swagger2配置 springboot配置swagger swagger2.9.2报错 swagger入门配置 springboot

本文链接：https://blog.csdn.net/w13657909078/article/details/89335175

版权

swagger2.9.2 专栏收录该内容

0 篇文章 1 订阅

订阅专栏

springboot项目整合swagger配置文件

本次使用的事swagger2.9.2版本，但是相对于2.8.2版本的，会存在一些问题，下面再详细说明

1，第一步，导入依赖包

	<dependency>
		<groupId>io.springfox</groupId>
		<artifactId>springfox-swagger2</artifactId>
		<version>2.9.2</version>
		<exclusions>
			<exclusion>
				<groupId>io.swagger</groupId>
				<artifactId>swagger-annotations</artifactId>
			</exclusion>
			<exclusion>
				<groupId>io.swagger</groupId>
				<artifactId>swagger-models</artifactId>
			</exclusion>
		</exclusions>
	</dependency>
	<dependency>
		<groupId>io.springfox</groupId>
		<artifactId>springfox-swagger-ui</artifactId>
		<version>2.9.2</version>
	</dependency>
	<dependency>
		<groupId>io.swagger</groupId>
		<artifactId>swagger-annotations</artifactId>
		<version>1.5.21</version>
	</dependency>
	<dependency>
		<groupId>io.swagger</groupId>
		<artifactId>swagger-models</artifactId>
		<version>1.5.21</version>
	</dependency>

注明：可能会有大兄弟发现，其他博客搜索到的依赖，只需要加两段就行了，为什么这里要加这么多，那是因为2.9.2版本的swagger在项目跑起来后会报下面的错误：

java.lang.NumberFormatException: For input string: “”
at java.lang.NumberFormatException.forInputString(NumberFormatException.java:65) ~[na:1.8.0_181]
at java.lang.Long.parseLong(Long.java:601) ~[na:1.8.0_181]
at java.lang.Long.valueOf(Long.java:803) ~[na:1.8.0_181]
at io.swagger.models.parameters.AbstractSerializableParameter.getExample(AbstractSerializableParameter.java:412) ~[swagger-models-1.5.20.jar:1.5.20]
at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method) ~[na:1.8.0_181]
at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62) ~[na:1.8.0_181]
at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43) ~[na:1.8.0_181]
at java.lang.reflect.Method.invoke(Method.java:498) ~[na:1.8.0_181]

所以，通过排除springfox-swagger2 引入的swagger-annotations、swagger-models 1.5.20版本，手动引入1.5.21版本的jar就可以解决这个问题。

2，项目中自建一个java配置文件的包，新增SwaagerConfig.java文件

package net.mrd.framework.config;

import java.util.ArrayList;
import java.util.List;
import org.springframework.beans.factory.annotation.Value;
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.ApiKey;
import springfox.documentation.service.AuthorizationScope;
import springfox.documentation.service.SecurityReference;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.contexts.SecurityContext;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**

主要是添加注解@EnableSwagger2和定义Docket的bean类。
*/

@Configuration
@EnableSwagger2
public class SwaggerConfig {

// 是否开启swagger，正式环境一般是需要关闭的，可根据Springboot的多环境配置进行设置
@Value(value = "${swagger.enabled}")
Boolean swaggerEnabled;

@Bean
public Docket createRestApi() {

	return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
			// 是否开启
			.enable(swaggerEnabled).select()
			// 扫描的路径包
			.apis(RequestHandlerSelectors.basePackage("net.mrd.controller"))
			// 指定路径处理PathSelectors.any()代表所有的路径
			.paths(PathSelectors.any()).build().pathMapping("/");
}

private ApiInfo apiInfo() {
	return new ApiInfoBuilder().title("SpringBoot-Swagger2集成")
	.description("myriadiot | migua")
	.version("2.9.2").build();
}

}

3，配置完这些，就可以去访问swagger的页面了 http://localhost:8000/swagger-ui.html#/ ,如下图
在这里插入图片描述
备注：假如你的登录拦截器里，有做拦截，那么在拦截器上排除掉需要
package net.mrd.framework.filter;

import net.mrd.service.CacheService;
import org.apache.commons.lang3.StringUtils;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Component;

import javax.servlet.*;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.io.IOException;

@Component
public class LoginFilter implements Filter {

@Autowired
private CacheService cacheService;

@Override
public void init(FilterConfig filterConfig) {
}

@Override
public void doFilter(ServletRequest servletRequest,
                     ServletResponse servletResponse,
                     FilterChain filterChain) throws IOException, ServletException {
    HttpServletRequest  request  = (HttpServletRequest) servletRequest;
    HttpServletResponse response = (HttpServletResponse) servletResponse;

    String uri = request.getRequestURI();

    if (uri.startsWith("/login") || uri.startsWith("/wechat") || uri.startsWith("/test") || uri.startsWith("/swagger")
    		|| uri.startsWith("/webjars") || uri.startsWith("/v2")) {
        filterChain.doFilter(servletRequest, servletResponse);
        return;
    }

    String token = request.getHeader("token");
    if (StringUtils.isBlank(token) || (cacheService.getAndRefreshUserCache(token) == null)) {
        response.setContentType("application/json;charset=utf8;");
        response.getWriter().write("{\"code\":1,\"msg\":\"会话过期\"}");
        response.getWriter().flush();
        return;
    }

    filterChain.doFilter(servletRequest, servletResponse);
}

@Override
public void destroy() {

}

}

4，如果你发现访问接口需要绕过 token验证，swagger2也有一个很简单的配置
只需要在SwaggerConfig.java文件中，加上下面的配置即可，（对照着看上面的配置文件加了那些内容）

package net.mrd.framework.config;

/**

主要是添加注解@EnableSwagger2和定义Docket的bean类。
*/

@Configuration
@EnableSwagger2
public class SwaggerConfig {

// 是否开启swagger，正式环境一般是需要关闭的，可根据Springboot的多环境配置进行设置
@Value(value = "${swagger.enabled}")
Boolean swaggerEnabled;

@Bean
public Docket createRestApi() {

	return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
			// 是否开启
			.enable(swaggerEnabled).select()
			// 扫描的路径包
			.apis(RequestHandlerSelectors.basePackage("net.mrd.controller"))
			// 指定路径处理PathSelectors.any()代表所有的路径
			.paths(PathSelectors.any()).build().pathMapping("/").securitySchemes(securitySchemes())
			.securityContexts(securityContexts());

}

private ApiInfo apiInfo() {
	return new ApiInfoBuilder().title("SpringBoot-Swagger2集成").description("myriadiot | migua")
			.version("2.9.2").build();
}

private List<ApiKey> securitySchemes() {
	List<ApiKey> apiKeyList = new ArrayList();
	apiKeyList.add(new ApiKey("token", "token", "header"));
	return apiKeyList;
}

// 过滤掉某些不需要token验证的接口（可有可无）
private List securityContexts() {
List securityContexts = new ArrayList<>();
securityContexts.add(SecurityContext.builder().securityReferences(defaultAuth())
.forPaths(PathSelectors.regex("^(?!auth).*$")).build());
return securityContexts;
}

List<SecurityReference> defaultAuth() {
	AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
	AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
	authorizationScopes[0] = authorizationScope;
	List<SecurityReference> securityReferences = new ArrayList<>();
	securityReferences.add(new SecurityReference("token", authorizationScopes));
	return securityReferences;
}

}

加上以上配置之后，页面上会多一个锁标志

在这里插入图片描述

5，使用方法，登录之后获取到token，手动复制粘贴到下面的框框里，点Authorize即可
在这里插入图片描述

6，最后一点，如果发现把token复制到那个框框里发现没起作用的时候，检查下面两个方法 apiKeyList.add(new ApiKey(“token”, “token”, “header”));里的第一个参数token 和 securityReferences.add(new SecurityReference(“token”, authorizationScopes));方法的第一个参数是否名字一致即可

private List securitySchemes() {
List apiKeyList = new ArrayList();
apiKeyList.add(new ApiKey(“token”, “token”, “header”));
return apiKeyList;
}
List defaultAuth() {
AuthorizationScope authorizationScope = new AuthorizationScope(“global”, “accessEverything”);
AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
authorizationScopes[0] = authorizationScope;
List securityReferences = new ArrayList<>();
securityReferences.add(new SecurityReference(“token”, authorizationScopes));
return securityReferences;
}

7.最后，在springboot的application.properties配置文件中加上swagger.enabled=true ，这个为swagger的开关，部署到正式服的时候，不需要使用swagger，设置成false即可

完结。
以上均是本人在公司项目中实战用到，测试均无问题，后续有时间会再更新swagger2的注解使用方法。敬请关注！

尖耳朵的阿凡达妹妹

关注

1
点赞
踩
2

收藏

觉得还不错? 一键收藏
0
评论
新手入门教你轻松为springboot项目搭建swagger2

springboot项目整合swagger配置文件本次使用的事swagger2.9.2版本，但是相对于2.8.2版本的，会存在一些问题，下面再详细说明1，第一步，导入依赖包 <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</a...
复制链接

扫一扫