技术求助：GitHub Pages部署Swagger-UI后Try-it-Out功能失效

Hey Mike, I’ve dealt with this exact problem before when getting Swagger-UI up on GitHub Pages—total headache when the UI loads but you can’t actually test endpoints. Let’s go through the most common fixes that worked for me:

1. Fix CORS Restrictions #

The #1 issue here is almost always cross-origin requests being blocked by the browser. GitHub Pages hosts your Swagger-UI on a domain like your-username.github.io, and if your API is on a different domain (e.g., api.your-app.com), browsers will block the Try-It-Out requests by default.

• If you control the API server, add CORS headers to allow requests from your GitHub Pages domain. For example, in Node.js/Express, you’d use something like:

  const cors = require('cors');
  app.use(cors({ origin: 'https://your-username.github.io' }));
  

• If you don’t control the API, you might need to use a CORS proxy (note: public proxies can be insecure for production use). Alternatively, check if the API provider offers a CORS-enabled endpoint or a JSONP option.

2. Correct Your OpenAPI Spec’s Server Paths #

Double-check your OpenAPI YAML/JSON file’s servers section. If you used a relative path (like /api/v1) during local development, that will point to https://your-username.github.io/api/v1 when deployed to GitHub Pages—which is not your actual API.

Update it to the full absolute URL of your API:

servers:
  - url: https://api.your-app.com/v1

3. Avoid Mixed Content Errors #

GitHub Pages serves content over HTTPS exclusively. If your API is still using HTTP, modern browsers will block the Try-It-Out requests as "mixed content". Make sure your API is also accessible over HTTPS—most hosting providers offer free SSL certificates these days.

4. Verify Swagger-UI Configuration #

Sometimes the issue is in how you’re initializing Swagger-UI. Ensure that tryItOutEnabled is set to true in your Swagger-UI config (it’s enabled by default, but it’s worth checking):

const ui = SwaggerUIBundle({
  url: "./openapi.yaml",
  dom_id: '#swagger-ui',
  tryItOutEnabled: true,
  // other config options
});

One last thing: after making changes, clear your browser cache or do a hard refresh (Ctrl+Shift+R) to make sure you’re not loading old assets from GitHub Pages.

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