Swagger ThreadLocal

一、Swagger 笔记1. 是什么（What）Swagger 是一款开源的 RESTful API 文档生成、在线调试工具，是目前前后端分离开发中 API 管理的行业标准解决方案，现已迭代至 OpenAPI 3.0 规范。核心本质：代码即文档，通过注解与业务代码绑定，自动生成实时同步的 API 文档，无需手动维护。主流实现分支：SpringFox：适配 SpringBoot 2.x，支持 Swagger2、Swagger3（OpenAPI 2.0），目前已停止维护。SpringDoc：适配 SpringBoot 2.x/3.x，全面支持 OpenAPI 3.0 规范，是 Spring 官方推荐的主流实现。核心能力：API 文档自动生成、接口在线调试、接口入参 / 出参模型自动说明、多环境权限控制。2. 为什么用（Why）核心解决前后端分离开发中的 API 协作痛点，替代传统手写 Word/Markdown 接口文档的模式，核心价值如下：解决文档与代码不同步问题传统手写文档更新滞后，接口字段、逻辑变更后极易出现文档与代码不一致，导致前后端联调扯皮；Swagger 注解与代码绑定，代码变更后文档自动同步，从根源解决一致性问题。降低接口调试成本无需额外借助 Postman 等工具，直接在可视化页面填写参数、发起请求、查看响应，支持 Header、Token、请求体等全场景参数配置，一键完成接口自测与联调。降低项目维护与新人上手成本提供统一的 API 文档入口，全项目接口分类展示、入参出参含义清晰，无需翻阅代码即可快速了解全量接口能力，新人上手效率大幅提升。无侵入式开发，接入成本极低仅通过注解配置即可完成能力接入，无需修改业务逻辑代码，对原有业务无侵入。3. 怎么做（How）以下分SpringBoot 3.x（SpringDoc OpenAPI3）和SpringBoot 2.x（SpringFox Swagger3）两个主流场景，提供可直接落地的使用步骤。场景 1：SpringBoot 3.x + SpringDoc（OpenAPI 3.0，推荐）步骤 1：引入 Maven 依赖xml!-- SpringDoc OpenAPI3 核心依赖 -- dependency groupIdorg.springdoc/groupId artifactIdspringdoc-openapi-starter-webmvc-ui/artifactId version2.5.0/version /dependency步骤 2：基础配置（application.yml）yamlspringdoc: api-docs: enabled: true # 开启api文档生成 path: /v3/api-docs # 文档json地址 swagger-ui: enabled: true # 开启可视化页面 path: /swagger-ui.html # 页面访问路径 tags-sorter: alpha # 接口按标签字母排序 operations-sorter: method # 接口按请求方式排序 # 多环境控制：生产环境可关闭swagger spring: profiles: active: dev --- spring: config: activate: on-profile: prod springdoc: api-docs: enabled: false swagger-ui: enabled: false步骤 3：全局文档配置（可选）java运行import io.swagger.v3.oas.models.OpenAPI; import io.swagger.v3.oas.models.info.Contact; import io.swagger.v3.oas.models.info.Info; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; @Configuration public class SpringDocConfig { @Bean public OpenAPI customOpenAPI() { return new OpenAPI() .info(new Info() .title("XX项目接口文档") /