java swagger ui 添加header请求头参数

本文介绍如何在Springfox框架下为Swagger UI的所有API接口统一添加Header参数'ticket',并提供了一个具体的Java配置示例。

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

我用到的swagger 主要有三款产品,swagger editor,swagger ui 和swagger codegen。

 swagger editor:主要是一个本地客户端,用来自己添加api,自己来测试,相当于一个api的可视化测试工具和定义工具吧。

 swagger ui:主要用户嵌入到项目中,将所有的接口生成一个可视化的页面,方便前后端联调

 swagger codegen:主要用于通过swagger来自动生成代码

我用的swagger ui主要在java项目中。将所有的http接口提供一个可视化页面。供前端同学看到,联调非常方便,所有的接口一目了然。

但是在使用swagger ui的时候,我有一个新的需求,就是我所有的接口都必须授权才能访问,即每个接口都必须添加一个header里的参数。一般用Authorization,但是我的键是ticket。于是尝试配置swagger,将每个接口都默认增加一个ticket的请求参数。

我在Java中用的swagger框架是springfox。springfox是比较新的,官方也一直在更新。java添加swagger我就不详细介绍了,这里只介绍如何在所有的swagger接口中默认都添加header参数

粘贴springfox配置如下:

package cn.ce.platform_service.interceptors;

import java.util.ArrayList;
import java.util.List;

import org.springframework.context.annotation.Bean;
import org.springframework.test.context.web.WebAppConfiguration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;

import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
* @Description : swagger配置配置
* @Author : Mars
* @Date : 2017年9月6日
*/
@WebAppConfiguration
@EnableSwagger2
@EnableWebMvc
//@ComponentScan(basePackageClasses = {ApisController.class }) //Instructs spring where to scan for API controllers
public class SwaggerConfig {
	
    /**
     * Every Docket bean is picked up by the swagger-mvc framework - allowing for multiple
     * swagger groups i.e. same code base multiple swagger resource listings.
     */
    @Bean
    public Docket customDocket(){
    	ParameterBuilder ticketPar = new ParameterBuilder();
        List<Parameter> pars = new ArrayList<Parameter>();  
    	ticketPar.name("ticket").description("user ticket")
    	.modelRef(new ModelRef("string")).parameterType("header") 
    	.required(false).build(); //header中的ticket参数非必填,传空也可以
    	pars.add(ticketPar.build());    //根据每个方法名也知道当前方法在设置什么参数
 
        return new Docket(DocumentationType.SWAGGER_2)
        		.select()
        		.apis(RequestHandlerSelectors.any())  
                .build()  
                .globalOperationParameters(pars)  
                .apiInfo(apiInfo());
    }
    
    ApiInfo apiInfo() {  
    	return new ApiInfoBuilder()  
            .title("api swagger document")  
            .description("前后端联调swagger api 文档")  
            .version("2.1.5.5")  
            .build();
    }  
}
修改swagger的配置文件如上即能满足swagger中所有的接口默认都加上ticket参数,非必填如下图:





### 如何在 Swagger 文档中全局配置默认请求头 为了在全球范围内为所有 API 接口添加自定义的请求头,可以基于不同的编程语言和框架采取相应的解决方案。以下是针对 ASP.NET Core 和 Java SpringFox 的具体方法。 #### 1. **ASP.NET Core 配置** 在 ASP.NET Core 中可以通过 `OperationFilter` 来实现全局添加请求头的功能。通过扩展 `IOperationFilter` 并将其注册到 Swagger 配置中,可以在每个操作上自动注入指定的 Header 参数。 ```csharp public class AddRequiredHeaderParameter : IOperationFilter { public void Apply(OpenApiOperation operation, OperationFilterContext context) { if (operation.Parameters == null) operation.Parameters = new List<OpenApiParameter>(); operation.Parameters.Add(new OpenApiParameter { Name = "Authorization", In = ParameterLocation.Header, Description = "Bearer token to access the APIs", Required = true, Schema = new OpenApiSchema { Type = "string" } }); } } ``` 随后,在启动服务时将此过滤器应用到 Swagger: ```csharp services.AddSwaggerGen(c => { c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" }); c.OperationFilter<AddRequiredHeaderParameter>(); // 注册自定义过滤器 }); ``` 上述代码会确保所有 API 操作都会带有名为 `Authorization` 的头部字段[^1]。 --- #### 2. **SpringFox(Java)中的配置** 对于使用 SpringFox 的项目,可以通过创建一个 Bean 实现 `OperationBuilderPlugin` 或者直接利用现有的插件机制来完成同样的功能。 下面是一个简单的例子展示如何向每一个接口添加固定的 Header 请求参数: ```java import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger.common西斯.Xxx; // 导入必要的包... @Component public class CustomGlobalHeader implements Plugin { @Override public boolean supports(DocumentationType delimiter) { return DocumentationType.SWAGGER_2.equals(delimiter); } @Override public void apply(OperationContext context) { context.operationBuilder().parameters( Arrays.asList( new ParameterBuilder() .name("X-Custom-Token") // 自定义名称 .description("Custom Token for Authentication") .modelRef(new ModelRef("string")) .parameterType("header") .required(true).build()) ); } } @Bean public Docket apiDocumentation(CustomGlobalHeader customGlobalHeader){ return new Docket(DocumentationType.SWAGGER_2) .globalOperationParameters(customGlobalHeader.apply(null)) ...其他配置... } ``` 这段代码片段展示了如何构建并注册一个新的全局 Header 参数给所有的 API 路径[^2]。 --- #### 3. **Knife4j 生产环境下隐藏文档资源** 如果希望进一步控制不同运行环境中是否暴露这些敏感信息,则推荐使用 Knife4j 提供的相关特性。只需简单调整 YAML 文件即可轻松切换开发与生产的模式设置而无需额外编写逻辑代码处理环境差异问题。 例如,在生产环境中完全禁用掉对外可见的部分内容可通过如下方式快速达成目标: ```yaml server: port: 8080 spring: profiles: prod # 设置当前激活的是prod文件夹下的application-prod.yml或者其他形式加载特定profile的方式均可生效。 knife4j: enable: false # 关闭增强UI界面效果等功能模块开关,默认true开启状态;此处设false即关闭整个前端美化样式呈现部分。 production: true # 启用生产模式下的一些特殊行为比如隐藏某些按钮链接之类的交互细节表现优化措施等。 ``` 当设置了以上属性之后,即使访问地址正确也无法查看任何关于API描述方面的资料了[^3]。 --- ### 总结 无论是哪种技术栈都可以找到合适的方法去满足业务需求——既能在测试阶段方便调试又能保障正式上线后的安全性考虑周全。关键是理解各自工具链的工作原理以及灵活运用它们所提供的强大定制能力!
评论 13
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值