讯享网

 <p><strong>basepath</strong> 是 Swagger 用来指定 API 的基本路径的一个选项。它用于设置 API 的基本路径，在使用 Swagger 编写 API 文档时，通过设置 basepath，可以统一设置 API 的前缀路径，方便 API 管理和调用。设置 basepath 可以为整个 API 文档中的所有路径添加一个前缀。这个前缀可以是一个 URL 路径，例如/api 或者/v1，用于区分不同的版本或者模块。</p><figure class="kg-card kg-image-card kg-card-hascaption"><img src="https://apifox.com/apiskills/content/images/2023/10/image-82.png" class="kg-image" alt="Swagger" loading="lazy" width="1280" height="676" srcset="https://apifox.com/apiskills/content/images/size/w600/2023/10/image-82.png 600w, https://apifox.com/apiskills/content/images/size/w1000/2023/10/image-82.png 1000w, https://apifox.com/apiskills/content/images/2023/10/image-82.png 1280w" sizes="(min-width: 720px) 720px"><figcaption>Swagger</figcaption></figure><p></p><p>设置 basepath 在以下情况下特别有用：</p><ul><li>当使用多个版本的 API 时，可以通过为每个版本设置不同的 basepath 来方便地进行版本管理。</li><li>当使用模块化的系统时，可以根据每个模块设置不同的 basepath，方便进行模块化管理。</li><li>在进行 API 代理时，可以将所有请求代理到不同的基本路径下的不同服务上。<br></li></ul><p>在 Swagger 中，你可以使用 "basePath" 关键字来指定 basepath。在 Swagger YAML 或 JSON 文件的根级别中，可以将 "basePath" 添加为属性来定义 basepath for your API。示例如下：</p><p><br>Swagger YAML 文件示例：</p><pre></pre><p><br>Swagger JSON 文件示例：</p><pre></pre><p><br>在这个示例中，"basePath" 被设置为 "/v1"，因此对于所有端点路径，都将相对于这个 basepath 进行定义。</p><p><br>在使用 Swagger UI 或其他 Swagger 工具查看 API 文档时，会自动应用这个 basepath。也就是说，当你在 Swagger UI 中测试 API 时，所有请求的 URL 都将在 basepath 的前面添加。<br><br></p><p>为了更好地理解 Swagger basepath 的用法，我们来看一个具体的示例。假设我们正在构建一个电商平台的 API，并且希望将所有商品相关的 API 路径统一设置为。</p><p><br>下面是一个在 Swagger editor 中运行的示例代码：</p><pre></pre><p>在上面的示例中，我们在 basePath 字段中设置了作为基本路径，这样所有的 API 路径都会添加前缀。</p><figure class="kg-card kg-image-card kg-card-hascaption"><img src="https://apifox.com/apiskills/content/images/2023/10/image-83.png" class="kg-image" alt="Swagger Editor 的 basePath 示例" loading="lazy" width="1280" height="671" srcset="https://apifox.com/apiskills/content/images/size/w600/2023/10/image-83.png 600w, https://apifox.com/apiskills/content/images/size/w1000/2023/10/image-83.png 1000w, https://apifox.com/apiskills/content/images/2023/10/image-83.png 1280w" sizes="(min-width: 720px) 720px"><figcaption>Swagger Editor 的 basePath 示例</figcaption></figure><p></p><p>在 Spring Boot 项目中，你可以使用注解中的属性或属性来指定 basepath。</p><p><br>示例代码：</p><pre></pre><p>在这个示例中，注解中的或属性被设置为"/api/v1"，作为 basepath。所有在类中的端点路径将相对于这个 basepath 进行定义。</p><p><br>例如，如果在中有一个端点映射为，则实际的访问路径将是。</p><p><br>请确保在 Spring Boot 应用程序中正确定义和配置了和注解，以便将 basepath 应用于所有端点。<br><br></p><p>在使用 Swagger basepath 时需要注意以下几点：</p><ul><li><strong>避免重复的基础路径</strong>：不要在 basepath 中包含重复的路径部分。例如，如果 API 的实际部分中已经包含了的路径，那么不需要在 basepath 中再次包含它。</li><li>确保 basepath 的设置与 API 的实际路径相匹配，防止路径冲突导致 API 无法访问。</li><li>你可以设置空字符串（""）作为 basepath，以移除路径前缀。</li><li>Swagger 语法版本可能会对 basepath 的解析有所不同，请根据所使用的 Swagger 版本进行相应的配置。<br><br></li></ul><p>要避免基础路径的重复部分，可以采取以下几种方法：<br></p><ol><li>通过配置服务器的反向代理：如果使用反向代理服务器（例如 Nginx），可以将重复的基础路径配置在反向代理服务器中，然后将请求转发到应用程序。这样，应用程序中的 basepath 就只需要包含自定义的部分。<br></li><li>使用 Spring Boot 的 context-path 属性：在 Spring Boot 应用程序的配置文件（如 application.properties 或 application.yml）中设置属性。将重复的基础路径部分配置为 context-path 的值。这将自动在所有的请求路径前添加指定的基础路径。   示例：在 application.properties 中配置 context-path</li></ol><pre></pre><p></p><p>3. 使用统一的变量或常量：将重复的基础路径部分定义为一个变量或常量，并在需要使用到的地方进行引用。这样可以确保在多个地方同时进行修改，并避免硬编码的重复路径。   示例：在 Java 中定义基础路径的常量</p><pre></pre><p><br>通过以上方法，你可以避免重复的基础路径部分，提高代码的可维护性，并确保在不同环境中正确地设置和处理基础路径。<br></p><p>Swagger 管理接口有时很不方便，缺乏一定的安全性和团队间的分享协作，所以我更推荐使用 Apifox 的 IDEA 插件。你可以在 IDEA 中自动同步 Swagger 注解到 Apifox，一键生成接口文档，多端同步，非常方便测试和维护，这样就可以迅速分享 API 给其他小伙伴。</p><figure class="kg-card kg-image-card kg-card-hascaption"><img src="https://apifox.com/apiskills/content/images/2023/10/image-84.png" class="kg-image" alt="Apifox 的 IDEA 插件" loading="lazy" width="1280" height="834" srcset="https://apifox.com/apiskills/content/images/size/w600/2023/10/image-84.png 600w, https://apifox.com/apiskills/content/images/size/w1000/2023/10/image-84.png 1000w, https://apifox.com/apiskills/content/images/2023/10/image-84.png 1280w" sizes="(min-width: 720px) 720px"><figcaption>Apifox 的 IDEA 插件</figcaption></figure><p>Apifox 是一个比 Postman 更强大的接口测试工具，Apifox = Postman + <strong>Swagger</strong> + Mock + JMeter，Apifox 支持调试 http（s）、WebSocket、Socket、gRPC、Dubbo 等协议的接口，并且集成了 IDEA 插件。</p><p><br>Apifox 的 IDEA 插件可以自动解析代码注释，并基于 Javadoc、KDoc 和 ScalaDoc 生成 API 文档。通过 IntelliJ IDEA 的 Apifox Helper 插件，开发人员可以在不切换工具的情况下将他们的文档与 Apifox 项目同步。</p><figure class="kg-card kg-image-card kg-card-hascaption"><img src="https://apifox.com/apiskills/content/images/2023/10/image-85.png" class="kg-image" alt="Apifox Helper" loading="lazy" width="1280" height="755" srcset="https://apifox.com/apiskills/content/images/size/w600/2023/10/image-85.png 600w, https://apifox.com/apiskills/content/images/size/w1000/2023/10/image-85.png 1000w, https://apifox.com/apiskills/content/images/2023/10/image-85.png 1280w" sizes="(min-width: 720px) 720px"><figcaption>Apifox Helper</figcaption></figure><p><br><strong>当在 IDEA 项目中有接口信息变动，只需右键点击「 Upload to Apifox」一键即可完成同步，无需奔走相告。</strong>团队成员可在 Apifox 中看到同步后的最新内容。</p><figure class="kg-card kg-image-card kg-card-hascaption"><img src="https://apifox.com/apiskills/content/images/2023/10/image-86.png" class="kg-image" alt="Apifox 的 IDEA 插件一键上传接口" loading="lazy" width="850" height="503" srcset="https://apifox.com/apiskills/content/images/size/w600/2023/10/image-86.png 600w, https://apifox.com/apiskills/content/images/2023/10/image-86.png 850w" sizes="(min-width: 720px) 720px"><figcaption>Apifox 的 IDEA 插件一键上传接口</figcaption></figure><p><br>现在出发去 JetBrains 插件市场 下载试试吧！或直接在 IDEA 内 「plugin」入口直接搜索 <strong>Apifox Helper</strong>。</p><figure class="kg-card kg-image-card kg-card-hascaption"><img src="https://apifox.com/apiskills/content/images/2023/10/image-87.png" class="kg-image" alt="Apifox 接口调试界面" loading="lazy" width="1280" height="810" srcset="https://apifox.com/apiskills/content/images/size/w600/2023/10/image-87.png 600w, https://apifox.com/apiskills/content/images/size/w1000/2023/10/image-87.png 1000w, https://apifox.com/apiskills/content/images/2023/10/image-87.png 1280w" sizes="(min-width: 720px) 720px"><figcaption>Apifox 接口调试界面</figcaption></figure><p><strong><em>知识扩展：</em></strong></p><ul><li><strong><em>Swagger Basic Authentication（身份验证）配置</em></strong></li><li><strong><em>Swagger 中添加 Bearer token 验证</em></strong></li></ul><p><br><br><em><strong>参考链接：</strong></em></p><ul><li><em>Swagger 官方文档：https://swagger.io/docs/specification/api-host-and-base-path/</em></li><li><em>SpringFox（SpringBoot 集成 Swagger 的工具）官方文档：https://springfox.github.io/springfox/docs/current/</em></li></ul>