如何在R Plumber的Swagger中添加带默认值的自定义HTTP请求头

1. 在Swagger中添加全局自定义请求头 #

要在Swagger界面添加可输入的HTTP_TENANT请求头（全局生效，所有接口自动继承该参数），需按照OpenAPI规范定义参数组件并全局引用。修改你的pr_set_api_spec函数如下：

library(plumber)

r <- plumber::pr("plumber.R") %>%
  plumber::pr_set_docs("swagger") %>%
  plumber::pr_set_api_spec(function(spec) {
    # 保留已实现的Bearer授权配置
    spec$components$securitySchemes$bearerAuth <- list(
      type = "http",
      scheme = "bearer",
      bearerFormat = "JWT"
    )
    spec$security <- list(list(bearerAuth = character(0)))
    
    # 定义全局自定义请求头参数
    spec$components$parameters$HTTP_TENANT <- list(
      name = "HTTP_TENANT",
      in = "header",  # 指定参数位置为请求头
      required = TRUE,  # 根据业务需求设置是否必填
      schema = list(type = "string"),
      description = "租户标识，用于区分不同客户"
    )
    # 将该参数设为全局参数，所有接口自动加载
    spec$parameters <- list("HTTP_TENANT")
    
    spec
  })

r %>% plumber::pr_run(port = 8000, host = '0.0.0.0')

修改后，Swagger界面顶部会出现HTTP_TENANT输入框，与Bearer授权区域相邻，所有接口请求都会自动携带该请求头。

2. 设置请求头和Bearer Token的默认值 #

给HTTP_TENANT设置默认值 #

直接在参数定义中添加default字段即可实现自动填充：

spec$components$parameters$HTTP_TENANT <- list(
  name = "HTTP_TENANT",
  in = "header",
  required = TRUE,
  schema = list(type = "string"),
  description = "租户标识，用于区分不同客户",
  default = "Customer name"  # 配置默认值
)

启动Swagger后，HTTP_TENANT输入框会自动填充该默认值。

给Bearer Token设置默认值 #

OpenAPI规范本身不支持直接给Bearer Auth配置默认值，需通过自定义Swagger UI的初始化脚本实现自动填充。修改pr_set_docs的配置，注入自定义JS代码：

r <- plumber::pr("plumber.R") %>%
  plumber::pr_set_docs(
    "swagger",
    ui = list(
      customJS = "
        window.addEventListener('load', function() {
          // 替换为实际的默认JWT令牌
          const defaultToken = 'your-default-jwt-token';
          const authBtn = document.querySelector('.btn.authorize');
          
          authBtn.addEventListener('click', function() {
            setTimeout(() => {
              const tokenInput = document.querySelector('input[name=\"bearerAuth\"]');
              if (tokenInput && tokenInput.value === '') {
                tokenInput.value = defaultToken;
              }
            }, 100);
          });
          
          // 若需页面加载后直接完成授权，可取消下方注释
          // authBtn.click();
        });
      "
    )
  ) %>%
  plumber::pr_set_api_spec(function(spec) {
    # 保留授权和请求头配置
    spec$components$securitySchemes$bearerAuth <- list(
      type = "http",
      scheme = "bearer",
      bearerFormat = "JWT"
    )
    spec$security <- list(list(bearerAuth = character(0)))
    
    spec$components$parameters$HTTP_TENANT <- list(
      name = "HTTP_TENANT",
      in = "header",
      required = TRUE,
      schema = list(type = "string"),
      description = "租户标识，用于区分不同客户",
      default = "Customer name"
    )
    spec$parameters <- list("HTTP_TENANT")
    
    spec
  })

将your-default-jwt-token替换为实际的默认令牌即可。这段代码会在Swagger页面加载后，监听授权按钮的点击事件，自动填充默认Token；若需要页面加载后直接完成授权，可取消注释authBtn.click();。

内容的提问来源于stack exchange，提问作者fifthace