如何优化Linux Swagger

在 Linux 环境下“优化 Swagger”通常涉及 性能、内存、启动速度、文档生成效率、API 响应速度 等方面。下面按常见场景给你一套实用优化方案，你可以对照自己的使用方式（Spring Boot / Node / Python / Nginx 等）进行裁剪。

一、明确你的 Swagger 使用方式

先确认你是哪种场景，不同场景优化点不同：

场景	说明
Spring Boot + Swagger / springdoc-openapi	最常见
Node.js + swagger-ui-express	前端或 BFF
Python + FastAPI / Flask	自动生成
静态 Swagger UI	仅展示文档
生产环境	是否对外暴露

二、通用优化建议（强烈推荐）

✅ 1. 生产环境禁用 Swagger

这是最重要的一条。

Spring Boot

spring:
  profiles: prod

@Profile("!prod")
@Configuration
public class SwaggerConfig {
    // Swagger 配置
}

或：

@Bean
public Docket api() {
    return new Docket(DocumentationType.OAS_30)
        .enable(false); // 生产环境关闭
}

✅ 好处：

减少内存占用
避免接口泄露
加快启动速度

✅ 2. 使用 springdoc-openapi 替代 Swagger 2（Spring Boot）

springdoc-openapi 更快、更轻量

<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
  <version>2.x</version>
</dependency>

优化点：

无反射缓存
启动更快
支持 Spring Boot 3

三、性能与内存优化

✅ 3. 减少扫描的 Controller 范围

避免扫描整个项目。

@Bean
public Docket api() {
    return new Docket(DocumentationType.OAS_30)
        .select()
        .apis(RequestHandlerSelectors.basePackage("com.xxx.api"))
        .paths(PathSelectors.any())
        .build();
}

❌ 不推荐：

.apis(RequestHandlerSelectors.any())

✅ 4. 减少 Swagger 注解数量

避免给 DTO 所有字段 加 @ApiModelProperty
使用默认值
删除无用 example

✅ 推荐：

public class UserDTO {
    private String name;
    private Integer age;
}

❌ 不推荐：

@ApiModelProperty(example = "Tom", required = true)

四、Swagger UI 加载优化（前端）

✅ 5. 使用 CDN 或本地缓存 Swagger UI

避免每次从 Maven / npm 解压。

Spring Boot 静态资源优化

spring:
  mvc:
    static-path-pattern: /static/**

或使用 Nginx：

location /swagger-ui/ {
    alias /usr/share/nginx/html/swagger-ui/;
    expires 30d;
}

✅ 6. 禁用 Swagger UI 的自动展开

减少 DOM 渲染压力。

<script>
  window.onload = function () {
    SwaggerUIBundle({
      url: "/v3/api-docs",
      dom_id: "#swagger-ui",
      docExpansion: "none"
    });
  };
</script>

五、Linux 系统层面优化

✅ 7. JVM 参数优化（Spring Boot）

-Xms256m
-Xmx512m
-XX:+UseG1GC

减少 Swagger 反射带来的 GC 压力。

✅ 8. 使用 Nginx 反向代理 + 缓存

location /v3/api-docs {
    proxy_pass http://localhost:8080;
    expires 10m;
}

六、API 文档本身优化

✅ 9. 分页 / 限制返回字段

避免 Swagger 示例数据过大。

@GetMapping("/list")
public Page<User> list(Pageable pageable) {
    return userService.list(pageable);
}

✅ 10. 拆分 API 文档

大型项目建议：

按模块拆分 api-docs
前端按需加载

@GroupedOpenApi
public static GroupedOpenApi adminApi() {
    return GroupedOpenApi.builder()
        .group("admin")
        .pathsToMatch("/admin/**")
        .build();
}

七、推荐的生产级最佳实践 ✅

✅ 生产环境必须：

关闭 Swagger
不暴露 /v3/api-docs
不暴露 /swagger-ui/**

✅ 开发环境：

开启
使用最小扫描范围
使用 springdoc

八、快速检查清单 ✅

项目	是否
生产环境禁用 Swagger	✅
限制扫描包	✅
使用 springdoc	✅
使用 CDN / 缓存	✅
减少注解	✅

如果你愿意，可以直接告诉我：

✅ 使用的语言 / 框架
✅ Linux 发行版
✅ 是否在生产环境
✅ 当前启动慢 / 内存高 / 访问慢？

我可以给你 针对性的优化方案或配置示例。