hapi-swagger返回JSON数据但无UI，/documentation端点404

既然你能正常访问/swagger.json拿到数据，说明核心的Swagger数据生成逻辑没问题，问题大概率出在UI页面的路由挂载上。我给你梳理几个最常见的排查和解决步骤：

1. 检查hapi-swagger的UI配置 #

先确认你的swaggerOptions里没有禁用UI，最好显式指定文档路径（默认就是/documentation，但有时候会被意外覆盖）：

const swaggerOptions = {
  info: {
    title: '你的API文档',
    version: '1.0.0',
  },
  // 显式声明文档页面路径，确保和你访问的一致
  documentationPath: '/documentation',
  // 注意不要设置disableUI: true（默认是false，不用特意写，但如果之前加了一定要删掉）
};

2. 确认插件加载顺序 #

hapi-swagger依赖Inert和Vision来提供静态资源（UI的HTML、CSS、JS文件），所以必须先注册Inert和Vision，再注册hapi-swagger。你的plugins数组写法看起来没问题，但可以再核对一下完整的注册逻辑：

const init = async () => {
  const server = Hapi.server({
    port: 3000,
    host: 'localhost'
  });

  // 先注册依赖插件，再注册swagger
  await server.register([
    Inert,
    Vision,
    {
      plugin: HapiSwagger,
      options: swaggerOptions
    }
  ]);

  // 注册你的API路由
  server.route([
    { 
      method: 'GET', 
      path: '/blah/albums', 
      options: { tags: ['api'], handler: () => ({ data: '示例返回' }) } 
    }
  ]);

  await server.start();
  console.log('服务器运行在: %s', server.info.uri);
};

init();

如果把hapi-swagger放在Inert/Vision前面注册，会导致它无法加载静态资源，自然找不到/documentation页面。

3. 排查路由冲突 #

有没有可能你自己定义了通配符路由（比如/*），并且放在了swagger插件注册之前？这种情况下，请求会被自定义路由拦截，导致swagger的/documentation路由无法匹配。解决办法是调整路由顺序，把自定义API路由放在前面，让swagger自动生成的路由优先级正常生效。

4. 验证版本兼容性 #

hapi和hapi-swagger的版本不兼容也会出问题，比如：

• @hapi/hapi 20+ 需要搭配hapi-swagger 14.x及以上版本
• 更老的hapi版本要对应匹配的hapi-swagger版本

可以试着重新安装依赖，确保版本适配：

npm uninstall @hapi/inert @hapi/vision hapi-swagger
npm install @hapi/inert @hapi/vision hapi-swagger

5. 查看服务器启动日志 #

启动服务器时，留意日志输出。如果hapi-swagger注册成功，会打印类似Added route: GET /documentation的日志。如果没看到这条日志，说明插件没正确注册，得回头检查插件配置或注册代码。

按上面的步骤排查，基本就能解决/documentation 404的问题了。

内容的提问来源于stack exchange，提问作者steve-o