RuoYi-Vue3项目Swagger接口文档端口配置优化指南

在RuoYi-Vue3这类前后端分离的企业级开发框架中，Swagger作为API文档工具发挥着重要作用。本文将深入探讨如何优化Swagger的配置，特别是解决端口号显示问题，帮助开发者更好地管理API文档。

问题背景分析

在RuoYi-Vue3框架的默认配置中，Swagger界面显示的接口地址会自动带上8080端口号。这种配置在某些部署环境下可能会导致404访问错误，特别是当：

1. 使用Nginx等转发服务器时
2. 部署在非标准端口环境下
3. 前后端分离部署架构中

解决方案详解

通过修改后端配置文件，我们可以轻松解决这个问题。关键在于调整Swagger的pathMapping配置项：

# Swagger配置
swagger:
  # 是否开启swagger
  enabled: true
  # 请求前缀
  pathMapping: 

将pathMapping留空后，Swagger将不再自动添加端口号到接口地址中。这种配置方式更加灵活，适用于各种部署环境。

技术原理深入

Swagger的pathMapping配置项原本设计用于处理以下场景：

1. 应用部署在子路径下时（如/context-path）
2. 需要自定义API前缀时
3. 转发场景下的路径重写

当不配置pathMapping时，Swagger会使用相对路径生成接口文档，这样就能自动适应各种部署环境，不会强制添加端口号。

最佳实践建议

1. 开发环境：可以保留默认配置，便于本地调试
2. 测试环境：建议清空pathMapping，模拟生产环境
3. 生产环境：必须清空pathMapping，确保接口文档可用性

配置注意事项

1. 修改配置后需要重启应用生效
2. 确保前后端的跨域配置正确
3. 如果使用HTTPS，需要相应调整Swagger的scheme配置

通过以上优化，RuoYi-Vue3项目的Swagger接口文档将更加灵活可靠，能够适应各种复杂的部署环境，为开发团队提供更好的API文档体验。