Swagger UI Express：未填必填参数时如何禁用Execute按钮？

1. 优先升级Swagger UI Express版本 #

旧版本（尤其是v4.0.0之前）存在UI校验逻辑bug，导致必填路径参数未填写时Execute按钮不会被禁用。执行升级命令：

npm update swagger-ui-express

2. 修正OpenAPI定义的语法问题 #

你的swagger.json中存在字符串引号不规范的问题（summary用了单引号，JSON要求双引号），这会导致Swagger UI解析定义时出错，无法识别必填参数规则。修正后的参数定义示例：

"/clientes/{codCliente}": {
  "get": {
    "summary": "Obter cliente por código",
    "description": "Retorna os dados de um cliente com base no código fornecido",
    "tags": ["Clientes"],
    "security": [...],
    "parameters": [
      { 
        "in": "path",
        "name": "codCliente",
        "description": "Código do cliente",
        "required": true,
        "type": "integer"
      }
    ],
    "responses": {
      "200": {
        "description": "Cliente encontrado com sucesso"
      }
    }
  }
}

3. 确保Swagger UI内置校验生效 #

在Swagger UI Express的配置中，显式启用本地校验（默认已开启，但可手动确认）：

const swaggerUi = require('swagger-ui-express');
const swaggerDocument = require('./swagger.json');

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument, {
  validatorUrl: null, // 禁用远程校验，仅使用本地规则校验
  displayOperationId: true
}));

4. 自定义脚本强制校验（临时修复） #

如果上述方法无效，可注入自定义前端脚本，手动监听参数输入并控制按钮状态：

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument, {
  customJs: `
    // 监听参数输入变化，实时更新按钮状态
    const updateExecuteBtnStatus = () => {
      const executeBtn = document.querySelector('.swagger-ui .btn.execute');
      if (!executeBtn) return;
      // 获取所有路径参数输入框
      const pathParamInputs = document.querySelectorAll('.parameter__path input');
      const allParamsFilled = Array.from(pathParamInputs).every(input => input.value.trim() !== '');
      executeBtn.disabled = !allParamsFilled;
    };

    // 页面加载时初始化状态
    window.addEventListener('load', updateExecuteBtnStatus);
    // 监听输入框变化
    document.addEventListener('input', updateExecuteBtnStatus);
    // 切换API操作时重新校验
    document.addEventListener('click', (e) => {
      if (e.target.closest('.operation-tag')) {
        setTimeout(updateExecuteBtnStatus, 100);
      }
    });
  `
}));

问题原因说明 #

出现这个情况通常是两个原因：一是Swagger UI版本过低，内置的参数校验逻辑未正确触发；二是OpenAPI定义存在语法错误（如引号不规范），导致UI无法正确解析必填参数的约束规则，进而没有禁用Execute按钮。点击后因参数缺失导致请求构建失败，前端状态异常，出现无法停止的加载动画。

内容的提问来源于stack exchange，提问作者Leonardo B. M.