使用play-swagger在localhost无法查看swagger json的问题求助

Hey there, let's dig into why your Swagger UI is only showing a green screen instead of your API docs—this is a super common gotcha even when following docs step-by-step. Here are the most likely fixes to check in order:

1. Verify the swagger.json endpoint is accessible first #

The Swagger UI loads your spec via the ?url=/assets/swagger.json parameter, so start by visiting http://localhost:9000/assets/swagger.json directly in your browser.

• If you get a 404: Your static asset mapping is broken. Double-check if your framework is configured to serve files from the /assets directory, or if the plugin generating swagger.json is outputting it to the correct folder. Some Swagger plugins require explicit config to write the generated JSON to your public assets folder.
• If you get invalid JSON or an empty object: The spec generation failed—either your base swagger.yml has syntax errors, or your route annotations aren't being scanned properly.

2. Check for syntax errors in your spec files/annotations #

Even a tiny typo can break the entire spec:

• Copy the content of your swagger.yml (or the generated swagger.json) into an OpenAPI validator tool (use a local desktop editor or the built-in validator in Swagger UI's dev tools) to catch missing commas, incorrect schema fields, or invalid HTTP method definitions.
• Double-check your route annotations: Make sure you're using the correct syntax for your framework's Swagger plugin (e.g., @swagger vs @openapi, proper indentation in multi-line annotations). A missing quote or misspelled field like summery instead of summary will mess up the generated spec.

3. Inspect browser developer tools for clues #

Hit F12 to open your browser's dev tools, then check two tabs:

• Network: Look for the request to swagger.json—note its status code (404, 500, 200?) and response content. A 500 means your server is throwing an error when generating the spec.
• Console: Look for JavaScript errors like Failed to fetch or Invalid JSON payload. These will tell you exactly why the UI can't load your spec (e.g., silent dependency failures or unexpected spec formatting).

4. Validate plugin and dependency compatibility #

Sometimes the issue is a version mismatch:

• Double-check that the Swagger plugin version you're using is compatible with your framework's major version (e.g., if you're using Fastify, confirm the plugin supports your Fastify version).
• Ensure you've installed all required peer dependencies—some Swagger plugins don't install these automatically, leading to silent failures during spec generation.

5. Check plugin initialization and route order #

If your framework relies on middleware/route order (like Express or Fastify):

• Make sure you initialize the Swagger plugin before registering your routes. If you register routes first, the plugin won't scan them to generate the spec, resulting in an empty swagger.json.
• Verify that the plugin is configured to scan the correct directory for routes with annotations—some plugins require explicit paths to your route files.

6. Test the Swagger UI URL with an absolute path #

Try replacing the relative URL in the query parameter with an absolute one to rule out path resolution issues:

http://localhost:9000/docs/swagger-ui/index.html?url=http://localhost:9000/assets/swagger.json

If this works, the issue is that the relative path /assets/swagger.json is being resolved incorrectly relative to the Swagger UI's base path.

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