SpringBoot整合Swagger3+Knife4j美化+携带请求头Token+Nginx代理转发请求配置

最新推荐文章于 2024-07-29 23:02:20 发布

你与谁结伴前来

最新推荐文章于 2024-07-29 23:02:20 发布

阅读量2.9k

点赞数 1

本文链接：https://blog.youkuaiyun.com/m0_63503620/article/details/130010296

版权

文章介绍了如何在SpringBoot项目中集成Swagger3和Knife4j，用于生成RESTfulAPI的文档。内容包括添加相关依赖，使用关键注解如@Tag、@Operation和@Schema，配置@EnableOpenApi和@EnableKnife4j，以及Nginx的配置以代理API访问。此外，还提到了访问路径和效果展示，以及解决鉴权问题的方法。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

依赖

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>${io.springfox.version}</version>
        </dependency>
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <version>${knife4j.version}</version>
        </dependency>
         <io.springfox.version>3.0.0</io.springfox.version>
         <knife4j.version>3.0.3</knife4j.version>

常用注解

@Tag：标识Controller

@Operation：标识方法

@Schema：标识字段

常用三个注解，其他不再赘述，请自行百度。

配置类和配置文件

@EnableOpenApi
@Configuration
@EnableKnife4j
public class Swagger3Config {

	//服务名称
	@Value("${swagger3.name}")
	private String name;
	//开关
	@Value("${swagger3.enable}")
	private Boolean enable;
	//版本
	@Value("${swagger3.version}")
	private String version;
	//描述
	@Value("${swagger3.description}")
	private String description;
	//分组
	@Value("${swagger3.group}")
	private String group;
	//扫描路径
	@Value("${swagger3.selector}")
	private String selector;

	@Bean
	public Docket docketForCommon(Environment environment) {
		// 如果没有配置开关 那么开发测试环境打开、正式环境关闭
		if (enable == null){
			//设置要显示的swagger环境
			Profiles profiles = Profiles.of("dev","test");
			//判断当前环境是否为开发测试环境
			enable = environment.acceptsProfiles(profiles);
		}
		return new Docket(DocumentationType.OAS_30)
			.apiInfo(apiInfo())//文档基础信息
			//整合请求头authorization 原生页面传参时需要手动去掉Bearer
			.securitySchemes(Collections.singletonList(HttpAuthenticationScheme.JWT_BEARER_BUILDER
				.name("Authorization")//页面展示字段
				.build()))
			.securityContexts(Collections.singletonList(SecurityContext.builder()
				.securityReferences(Collections.singletonList(SecurityReference.builder()
					.scopes(new AuthorizationScope[0])
					.reference("Authorization")
					.build()))
				.operationSelector(o -> o.requestMappingPattern().matches("/.*"))// 声明作用域
				.build()))
			.groupName(group)// 分组信息 多人开发注册多个bean
			.enable(enable)// 是否启用
			.select()
			//.withClassAnnotation(RestController.class)表示扫描类上有@RestController注解的类上接口
			//.withMethodAnnotation(GetMappering)扫描GetMappering方法接口
			.apis(RequestHandlerSelectors.basePackage(selector))// .basePackage()扫描指定路径下的所有接口 .any() 全扫描 .none() 全不扫描
			.paths(PathSelectors.any())//路径过滤
			.build();
	}

	private ApiInfo apiInfo() {
		return new ApiInfoBuilder()
			.title(name)//标题
			.description(description)//描述
			.version(version)//版本
			.build();
	}

# swagger3配置
swagger3:
  # 服务名称
  name: test
  # 是否启动
  enable: true
  # 项目版本
  version: v1.0.0
  # 文档描述
  description: Test说明文档
  # 分组信息
  group: common
  # 扫描路径
  selector: com.test.testController

Nginx配置

其中：

/v3、/swagger-resources、/swagger-ui、/swagger-ui/index.html为原生Swagger3需要请求的路径/资源。

/webjars、/favicon.ico/、/doc.html为knief4j美化需要请求的路径/资源。

proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-Port $server_port;

暴露端口和ip，提供给swagger3进行测试请求。

		location ~* ^(/v3|/swagger-resources|/swagger-ui|/swagger-ui/index.html|/webjars/|/favicon.ico/|/doc.html) {
			proxy_redirect off;
			proxy_set_header X-Real-IP $remote_addr;
			proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
			proxy_set_header X-Forwarded-Proto $scheme;
			proxy_pass http://yourserver;
			proxy_set_header   X-Forwarded-Host  $host;
			proxy_set_header   X-Forwarded-Port  $server_port;

		}
        upstream yourserver{
           server ip:port;
        }

访问路径

原生url（本地）：http://localhost:port/swagger-ui/index.html
原生 url（线上）：https://ip:port/swagger-ui/index.html （nginx代理必须要用https）
Knife4j url（本地）: http://localhost:port/doc.html
Knife4j url（线上）：https://ip:port/doc.html （nginx代理必须要用https）

效果展示

原生：

knief4j：

一些可能的问题

项目内如jwt之类的鉴权功能记得放行。

		if (requestURI.startsWith("/swagger")||requestURI.startsWith("/v3")||requestURI.startsWith("/webjars")||requestURI.startsWith("/favicon")
			||requestURI.startsWith("/doc")||excludeUrls.contains(requestURI)) {
			//Swagger放行
			filterChain.doFilter(request, response);
        }