SpringDoc OpenAPI 如何禁用默认的Swagger Petstore示例

在基于SpringDoc OpenAPI构建的API文档项目中，开发者有时会遇到一个常见现象：Swagger UI界面默认加载了与项目无关的Swagger Petstore示例内容。这种情况并非系统错误，而是SpringDoc的默认行为设计。

现象解析

当开发者启动集成了SpringDoc OpenAPI的项目时，Swagger UI界面可能会同时显示两个API文档分组：

1. 开发者自定义的API文档（通常以服务命名）
2. 系统自带的Swagger Petstore示例（包含宠物、商店等测试接口）

这种设计初衷是为了方便开发者参考标准示例，但在生产环境或正式项目中，无关的示例内容会造成混淆，影响使用体验。

解决方案

SpringDoc提供了简洁的配置参数来禁用这个默认行为。开发者只需在项目配置文件中添加以下配置项：

YAML格式配置示例：

springdoc:
  swagger-ui:
    disable-swagger-default-url: true

Properties格式配置示例：

springdoc.swagger-ui.disable-swagger-default-url=true

技术原理

该配置项的作用机制是：

1. 默认情况下，SpringDoc会保留Swagger UI的默认配置，其中包括对知名示例项目petstore.swagger.io的引用
2. 当启用disable-swagger-default-url参数后，框架会移除这个预设的外部API文档引用
3. 系统仅保留当前项目扫描生成的API文档

最佳实践建议

1. 开发环境：可以保留默认示例作为参考，方便对照学习标准化的API文档格式
2. 生产环境：务必禁用此选项，避免暴露无关内容，同时提升界面整洁度
3. 微服务架构：在多模块项目中，建议统一配置此参数，保持各服务文档界面的一致性

通过这个简单的配置调整，开发者可以轻松控制Swagger UI的显示内容，打造更专业的API文档界面。