怎么优化Linux Swagger性能

在 Linux 环境下优化 Swagger（通常指 Swagger UI / Swagger Editor / Swagger 相关接口文档服务） 的性能，主要可以从 网络、服务器、应用、缓存、资源加载 等几个层面入手。下面按常见使用场景给你一个系统性的优化方案。

一、先明确你用的是哪种 Swagger

不同场景优化重点不同：

场景	优化重点
Spring Boot + springfox / springdoc-openapi	JVM、接口扫描、JSON 生成
Swagger UI 静态页面	前端资源加载、缓存
Swagger Editor	Node.js / 浏览器性能
API Gateway 聚合 Swagger	并发、缓存、带宽

二、减少 Swagger JSON 体积（最关键）

Swagger 慢，90% 是因为 /v2/api-docs 或 /v3/api-docs 太大。

1️⃣ 精简接口扫描范围

✅ 只扫描需要的包

@OpenAPIDefinition
@SpringBootApplication
public class Application {
}

springdoc:
  packages-to-scan: com.example.api
  paths-to-match: /api/**

或 springfox：

@EnableSwagger2
@Configuration
public class SwaggerConfig {
    return new Docket(DocumentationType.OAS_30)
        .select()
        .apis(RequestHandlerSelectors.basePackage("com.example.api"))
        .paths(PathSelectors.ant("/api/**"))
        .build();
}

2️⃣ 忽略不相关接口

@ApiIgnore
@RestController
public class InternalController {
}

或：

@Operation(hidden = true)
@GetMapping("/internal")
public String internal() {}

3️⃣ 关闭不必要的 Schema 细节

springdoc:
  default-flat-param-object: true
  model-converters:
    deprecating-converter:
      enabled: false

或关闭 example 生成：

springdoc:
  show-actuator: false

三、Swagger UI 性能优化（前端）

1️⃣ 使用 CDN 加载 Swagger UI

❌ 不推荐：

/webjars/swagger-ui

✅ 推荐：

<link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist/swagger-ui.css">
<script src="https://unpkg.com/swagger-ui-dist/swagger-ui-bundle.js"></script>

2️⃣ 开启浏览器缓存

Nginx 示例：

location ~* \.(js|css|html|json)$ {
    expires 7d;
    add_header Cache-Control "public, max-age=604800";
}

3️⃣ 减少 Swagger UI 初始化加载

const ui = SwaggerUIBundle({
  url: "/v3/api-docs",
  dom_id: '#swagger-ui',
  deepLinking: false,
  displayOperationId: false,
  defaultModelsExpandDepth: -1, // 不展开 models
  defaultModelExpandDepth: 1
});

四、Linux 服务器层面优化

1️⃣ 使用 Nginx 反向代理（强烈推荐）

server {
    listen 80;
    location /swagger/ {
        proxy_pass http://localhost:8080/;
        proxy_set_header Host $host;
    }
}

✅ 好处：

支持 gzip
支持缓存
减少应用服务器压力

2️⃣ 开启 Gzip 压缩

gzip on;
gzip_types application/json application/javascript text/css;
gzip_min_length 1k;

JSON 通常能压缩 60%~80%。

3️⃣ Linux 系统参数优化（高并发）

ulimit -n 65535

sysctl -w net.core.somaxconn=65535

五、Swagger 接口生成性能优化

1️⃣ 延迟加载 Swagger（生产环境建议关闭）

springdoc:
  api-docs:
    enabled: false
  swagger-ui:
    enabled: false

或者：

profiles: prod

2️⃣ 使用缓存 Swagger JSON

@Cacheable("swagger")
public String apiDocs() {
    return generateApiDocs();
}

六、Spring Boot 专用优化建议

1️⃣ 使用 springdoc-openapi 替代 springfox

✅ springdoc 更快、更轻、支持 WebFlux
❌ springfox 已停止维护

2️⃣ JVM 参数优化

-Xms512m
-Xmx512m
-XX:+UseG1GC

七、性能对比参考

优化项	效果
精简 API 扫描	⭐⭐⭐⭐⭐
关闭 Models	⭐⭐⭐⭐
Gzip	⭐⭐⭐⭐
CDN Swagger UI	⭐⭐⭐
禁用 Swagger（生产）	⭐⭐⭐⭐⭐

八、生产环境最佳实践 ✅

✅ 开发环境：开启 Swagger
✅ 测试环境：只读 Swagger
❌ 生产环境：关闭 Swagger 或加 IP 白名单

springdoc:
  api-docs:
    enabled: false

九、如果你愿意，我可以进一步帮你：

✅ 分析 你的 /v3/api-docs 为什么慢
✅ 给你 Spring Boot 专用 Swagger 最优配置
✅ 给你 Nginx + HTTPS + Swagger 完整配置
✅ 帮你判断 是否应该直接上 Knife4j / RapiDoc

你可以直接贴：

Spring Boot 版本
Swagger 类型（springfox / springdoc）
接口数量（大概）
是否部署在 Docker / K8s