Swagger UI使用JSON配置无法正常工作，请求排查原因

Hey there! Let’s break down the most likely reasons your Swagger UI is acting up after switching to JSON-based configuration— I’ve worked through a ton of these setups, so here’s where to start digging:

Since you’ve dumped SpringFox, you’re now working directly with the OpenAPI 3.0+ spec (not the old Swagger 2.0 that SpringFox used). It’s super easy to miss required fields or mess up syntax here. Common gotchas:

• Forgetting the openapi field (must be set to 3.0.x, like 3.0.3)
• Missing mandatory info properties: title and version are non-negotiable
• Typos in path operations (e.g., misspelling get as GET or missing a required responses block)
• Broken $ref links pointing to components that don’t exist

Paste your JSON into the OpenAPI Editor (a free online tool) to catch schema errors instantly— it’ll highlight exactly where you went wrong.

You’re probably using springdoc-openapi-starter-webmvc-ui (the modern, maintained replacement for SpringFox) now. Make sure:

• You’ve got the right dependency in your build file:
  Maven:

  <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
      <version>2.2.0</version> <!-- Grab the latest stable version -->
  </dependency>
  

  Gradle:

  implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.2.0'
  

• You’ve told Swagger UI where to find your custom JSON file. By default, it looks at /v3/api-docs (auto-generated by SpringDoc), but you need to override this. Add this to your application.properties:

  springdoc.swagger-ui.url=/path/to/your/openapi.json
  

  Or if you prefer Java config:

  @Configuration
  public class SwaggerUiConfig {
      @Bean
      public SwaggerUiConfigurer swaggerUiConfigurer() {
          return params -> params.setUrl("/path/to/your/openapi.json");
      }
  }
  

If Swagger UI can’t load your JSON, it’ll fail silently (or show a "Failed to load API definition" error). Test this first:

• Pop your JSON file in src/main/resources/static— this makes it accessible at http://localhost:8080/openapi.json (adjust the port/path as needed)
• Try accessing that URL directly in your browser. If you get a 404, the file isn’t being served. Check if you’ve got custom static resource config blocking it, or move the file to the right directory.

Even if you removed @EnableSwagger2 and the dependency, old config can linger and cause conflicts:

• Do a full search of your codebase for springfox references— check property files (application.properties/application.yml) for springfox.* settings, and any leftover config beans.
• Make sure you don’t have any other Swagger-related dependencies hanging around (like springfox-swagger-ui) that might be overriding SpringDoc’s setup.

Don’t skip this step!

• Look at your application startup logs— if there’s a bean loading error or config issue, it’ll be there.
• Open Swagger UI, then hit F12 to open dev tools. Check the Network tab: is your JSON file returning a 404 or 500? Check the Console tab for JavaScript errors that might be breaking the UI.

By default, SpringDoc serves Swagger UI at /swagger-ui.html. If you changed the path via properties (like springdoc.swagger-ui.path=/my-swagger), make sure you’re visiting the correct URL.

If you’ve gone through all these steps and still have issues, share a snippet of your OpenAPI JSON and your application config— that’ll help zero in on the problem!

内容的提问来源于stack exchange，提问作者Raj Rajeshwar Singh Rathore