Swagger UI仅渲染原始HTML而非正常页面问题排查求助

Let’s break down why your Swagger UI is only returning raw HTML instead of the interactive interface, and fix it step by step:

1. Fix the Swagger Route Middleware Setup #

Looking at your swagger-route.js, splitting swaggerUi.serve and swaggerUi.setup into separate router.use() calls can disrupt how Swagger’s static assets (CSS, JS, fonts) are served. These assets are critical for rendering the interactive UI—without them, you’ll only see raw HTML.

Update your swagger-route.js to combine the serve and setup logic into a single router.use() call:

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

// Combine serve and setup to ensure static assets are properly delivered
router.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));

module.exports = router;

2. Verify Swagger Output File Generation #

Double-check that your swagger-output.json is correctly generated and exists in your root directory. Run the swagger.js script explicitly to regenerate it:

node swagger.js

If the file is missing or corrupted, Swagger UI can’t load the schema data it needs, which often leads to fallback raw HTML.

3. Check Express Middleware Order #

In your main Express app file (e.g., app.js or server.js), ensure you mount your routes after essential middleware like express.json(), and that no middleware is intercepting static asset requests before they reach the Swagger route.

Example of correct middleware order:

const express = require('express');
const app = express();

// Essential middleware first
app.use(express.json());

// Then mount your routes
app.use('/', require('./routes/index'));

app.listen(3000, () => {
  console.log('Server running on localhost:3000');
});

4. Adjust Security Middleware (If Used) #

If you’re using security middleware like helmet, it might block external resources Swagger UI relies on (e.g., CDN-hosted CSS/JS). For example, Helmet’s Content Security Policy (CSP) can prevent these assets from loading, resulting in raw HTML.

If you use Helmet, update your CSP directives to allow Swagger’s required resources:

const helmet = require('helmet');
app.use(helmet.contentSecurityPolicy({
  directives: {
    defaultSrc: ["'self'"],
    styleSrc: ["'self'", "'unsafe-inline'", "https://cdnjs.cloudflare.com"],
    scriptSrc: ["'self'", "'unsafe-inline'", "https://cdnjs.cloudflare.com"],
    fontSrc: ["'self'", "https://cdnjs.cloudflare.com"],
  },
}));

5. Confirm Route Mounting in routes/index.js #

Your current route order (mounting /characters first, then the root route with Swagger) is fine, but double-check that no other route is overriding the /api-docs path before it reaches the Swagger router.

After making these changes, restart your server and visit http://localhost:3000/api-docs (with or without the trailing slash)—the interactive Swagger UI should render properly.

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