问题：Swagger 3.0默认访问页面地址是什么？

Question

**问题：Swagger 3.0 默认访问页面地址是什么？** 在使用 Swagger 3.0（也称为 OpenAPI 3.0）进行 API 文档自动化生成与展示时，开发者常会问：Swagger 3.0 默认的访问页面地址是什么？ 通常情况下，Swagger UI 的默认访问路径为 `http://localhost:<端口号>/<上下文路径>/swagger-ui.html` 或者某些新版本中使用 `http://localhost:<端口号>/<上下文路径>/swagger-ui/index.html`。但在 Springdoc OpenAPI（适用于 Spring Boot 项目的 Swagger 3.0 实现）中，默认访问地址是 `http://localhost:<端口号>/<上下文路径>/swagger-ui.html` 或 `http://localhost:<端口号>/<上下文路径>/swagger-ui/index.html`。 了解该默认地址有助于快速访问交互式文档界面，提升开发调试效率。

Answer 1

一、Swagger 3.0 默认访问页面地址概述

在现代 API 开发中，使用 Swagger（现为 OpenAPI）进行接口文档的自动生成与展示已成为标准实践。随着 OpenAPI 规范演进至 3.0 版本，其配套工具链也进行了相应的升级。

对于大多数基于 Spring Boot 的项目，若使用 Springdoc OpenAPI 实现 Swagger 3.0，则默认的交互式文档访问路径通常如下：

• http://localhost:<端口号>/<上下文路径>/swagger-ui.html
• http://localhost:<端口号>/<上下文路径>/swagger-ui/index.html

其中，<端口号> 是应用运行时所监听的 HTTP 端口，默认为 8080；<上下文路径> 则取决于项目的配置，例如 /api 或为空。

二、Swagger UI 路径演变与版本差异分析

早期版本的 Swagger UI 使用 swagger-ui.html 文件作为入口页面，而从某些新版本开始，尤其是引入了 WebJar 资源管理后，入口文件变更为嵌套在 swagger-ui/index.html 中。

版本类型	默认访问路径	说明
传统 Swagger UI	/swagger-ui.html	适用于旧版 Springfox 集成
Springdoc OpenAPI	/swagger-ui/index.html	推荐用于 Spring Boot 2.6+ 及以上版本

开发者可通过检查依赖库版本或查看生成的静态资源目录结构来确认具体路径。

三、常见问题排查与解决方法

当无法访问默认的 Swagger 页面时，可能的原因包括但不限于以下几点：

1. 未正确引入依赖包，如缺少 springdoc-openapi-starter-webmvc-ui
2. 配置文件中关闭了文档生成功能：springdoc.openapi.urls=
3. 安全框架拦截了访问路径，如 Spring Security 未开放对应 URL 权限
4. 项目上下文路径配置错误，导致实际访问路径不匹配

// 示例：Spring Boot 启动类中启用 OpenAPI
@SpringBootApplication
public class MyApplication {
    public static void main(String[] args) {
        SpringApplication.run(MyApplication.class, args);
    }
}

四、定制化与扩展建议

虽然默认路径方便快捷，但在生产环境中往往需要对 Swagger 页面路径进行自定义，以增强安全性或统一门户风格。

可以通过以下方式修改默认访问路径：

1. 在 application.properties 或 application.yml 中配置：

springdoc:
  swagger-ui:
    url: /custom/swagger-ui/index.html

1. 通过实现 WebMvcConfigurer 接口重定向路径
2. 结合 Nginx 或前端网关统一代理文档路径

graph TD
    A[开发环境] --> B(Swagger UI可用)
    C[测试环境] --> B
    D[生产环境] --> E[禁用或授权访问]