linux swagger常见错误有哪些

在 Linux 环境下使用 Swagger（OpenAPI） 时，常见问题通常来自配置、路径、权限、依赖和运行环境。下面按使用场景总结常见错误及解决方法。

一、Swagger UI 无法访问（404 / 空白页）

1. 路径配置错误

现象

• 访问 /swagger-ui.html 或 /swagger-ui/ 报 404
• 页面空白

常见原因

• Spring Boot 中未开启 Swagger
• 上下文路径（context-path）未拼接

解决

server:
  servlet:
    context-path: /api

访问地址应为：

http://ip:port/api/swagger-ui.html

2. 拦截器 / 安全框架拦截

现象

• 登录页跳转
• 403 / 401

解决（Spring Security 示例）

@Override
public void configure(WebSecurity web) {
    web.ignoring().antMatchers(
        "/swagger-ui.html",
        "/swagger-resources/**",
        "/v2/api-docs",
        "/webjars/**"
    );
}

二、Linux 权限与文件问题

3. 无法读取配置文件

现象

Permission denied
FileNotFoundException

原因

• Swagger 配置或注解扫描路径无权限
• jar 包运行用户无权访问目录

解决

chown -R appuser:appuser /opt/app
chmod 755 /opt/app

4. SELinux 限制（CentOS / RHEL）

现象

• 本地能访问，Linux 上不能
• 日志无明显错误

排查

getenforce

临时解决

setenforce 0

三、端口与防火墙问题

5. 端口未开放

现象

• 本机 curl 正常
• 外部无法访问

解决

firewall-cmd --add-port=8080/tcp --permanent
firewall-cmd --reload

四、Springfox / Swagger 版本问题

6. Spring Boot 2.6+ 兼容问题

现象

Unable to render this definition
Failed to load API definition

原因

• Springfox 与 Spring Boot 2.6+ 不兼容

解决

spring:
  mvc:
    pathmatch:
      matching-strategy: ANT_PATH_MATCHER

或改用 springdoc-openapi

五、springdoc-openapi 常见问题（Linux 也适用）

7. 访问 /swagger-ui.html 404

正确地址

/swagger-ui/index.html

8. 扫描不到接口

@OpenAPIDefinition
@SpringBootApplication

确保 Controller 在启动类同包或子包

六、Docker + Linux 场景

9. 容器内能访问，宿主机不能

原因

• 未映射端口

docker run -p 8080:8080 app

10. 时区导致文档异常

-e TZ=Asia/Shanghai

七、日志中常见报错速查

如果你能告诉我：

• 用的是 Springfox 还是 springdoc
• 是否 Docker / CentOS / Ubuntu
• 具体报错日志

我可以直接帮你定位到具体原因。