Swagger生成OpenAPI文档不完整且未读取配置文件问题排查

核心原因 #

你看到的仅生成openapi、paths、components字段，是因为Swagger默认只会扫描JAX-RS接口生成接口路径和组件定义，全局元信息（比如info、servers、tags）需要通过配置文件或代码注解补充——而配置文件未被加载，自然不会生成这些完整字段。下面是具体排查和解决步骤：

1. 配置文件的路径与命名必须严格匹配 #

Swagger OAS 3.x的JAX-RS集成默认只读取类路径根目录下的openapi-configuration.json或openapi-configuration.yaml：

• 如果你把配置放在WEB-INF下，必须在web.xml中显式指定路径：

  <servlet>
      <servlet-name>OpenApiServlet</servlet-name>
      <servlet-class>io.swagger.v3.jaxrs2.integration.OpenApiServlet</servlet-class>
      <init-param>
          <param-name>openApiConfigurationLocation</param-name>
          <param-value>/WEB-INF/openapi-configuration.json</param-value>
      </init-param>
      <load-on-startup>1</load-on-startup>
  </servlet>
  

• 文件名不能随便修改（比如改成swagger-config.json），除非通过上述init-param指定自定义路径。

2. 依赖版本必须统一且完整 #

别混搭Swagger 2.x和3.x的依赖，确保以下核心依赖版本一致：

<!-- Maven示例，版本统一用最新稳定版 -->
<dependency>
    <groupId>io.swagger.core.v3</groupId>
    <artifactId>swagger-jaxrs2</artifactId>
    <version>2.2.15</version>
</dependency>
<dependency>
    <groupId>io.swagger.core.v3</groupId>
    <artifactId>swagger-core</artifactId>
    <version>2.2.15</version>
</dependency>

如果缺失swagger-core，配置文件加载逻辑会直接失效。

3. 配置文件格式必须正确 #

配置内容必须嵌套在openAPI节点下，否则Swagger会静默忽略整个配置文件：

{
  "openAPI": {
    "info": {
      "title": "我的业务API",
      "version": "1.0.0",
      "description": "API接口文档"
    },
    "servers": [{"url": "http://localhost:8080/api/v1"}]
  }
}

检查JSON语法（比如引号、逗号），语法错误会导致配置加载失败。

4. Servlet初始化逻辑不能遗漏关键步骤 #

如果你自定义了SwaggerServletInitializer，必须调用父类的onStartup方法，否则默认配置加载逻辑不会执行：

public class MySwaggerInitializer extends SwaggerServletInitializer {
    @Override
    public void onStartup(ServletContext servletContext) throws ServletException {
        // 必须调用父类方法，否则配置文件加载逻辑不生效
        super.onStartup(servletContext);
        // 也可以在这里手动指定配置路径
        servletContext.setInitParameter("openApiConfigurationLocation", "/openapi-configuration.json");
    }
}

如果是JAX-RS嵌入式容器（比如Jersey嵌入Tomcat），SwaggerServletInitializer不会生效，需要手动加载配置：

// 在JAX-RS应用初始化时添加
OpenApiConfiguration config = new JsonOpenApiConfiguration().fromLocation("/openapi-configuration.json");
OpenApiContextLocator.getInstance().getOpenApiContext().setConfiguration(config);

5. 确认配置文件已被正确打包 #

• Maven/Gradle项目要把配置文件放在src/main/resources目录下，否则打包后不会进入WEB-INF/classes（类路径根目录）。
• 解压WAR包检查WEB-INF/classes下是否存在你的配置文件，不存在的话调整打包配置。

补充：用注解替代配置文件（临时方案） #

如果配置文件加载始终有问题，可以在JAX-RS应用类上直接加注解补全全局信息：

@ApplicationPath("/api")
@OpenAPIDefinition(
    info = @Info(title = "我的API", version = "1.0.0", description = "接口文档"),
    servers = @Server(url = "http://localhost:8080/api")
)
public class MyJaxrsApplication extends Application {
    // ...
}

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