如何在Swagger中添加API使用场景示例？有无可行替代方案？

一、Swagger原生实现方式 #

你可以通过以下几种方式在现有Swagger体系里添加业务场景级的多端点调用流程，同时保留原有的端点描述和调试功能：

• 利用OpenAPI自定义扩展字段：在你的OpenAPI spec的顶层info节点或者tags节点中添加x-use-cases这类自定义字段，把每个业务场景的调用步骤、参数示例、依赖关系写进去。比如：

  info:
    title: 你的API服务
    version: 1.0.0
    x-use-cases:
      - name: 用户创建并激活账号
        steps:
          1. 调用 `POST /users` 创建用户，请求体示例：`{"email": "user@example.com", "password": "Abc123!"}`
          2. 调用 `POST /users/{id}/verify` 传入邮箱验证码完成激活
          3. 调用 `GET /users/{id}` 确认账号状态为已激活
  

  新版Swagger UI会自动渲染这些自定义扩展内容，你也可以稍微调整UI的配置让展示更清晰。
• 通过Tag分组+描述写流程：把属于同一个业务场景的端点归到同一个Tag下，然后在Tag的description里详细写这个场景的调用顺序和注意事项。比如给「用户账号」Tag的描述里写清楚创建、激活、查询的完整流程，Swagger UI的Tag标签页会直接显示这段描述，用户看完就能按步骤操作对应的端点。
• 自定义Swagger UI插件：如果你的团队有前端能力，可以给Swagger UI加一个自定义插件，新增一个「业务场景」的Tab页，把所有预定义的多端点流程整理进去，每个步骤可以直接链接到对应的端点调试界面，完全不影响原有功能。

二、满足需求的替代方案（保留端点调试功能） #

如果原生Swagger的方式不够灵活，这些工具可以满足你的需求，同时保留类似Swagger的端点描述和调试能力：

• Postman集合：先导入你的OpenAPI spec生成基础的请求集合，然后在集合里创建文件夹对应每个业务场景，把需要调用的端点按顺序拖进去，给每个文件夹添加流程说明。Postman支持单独调试每个请求，也能一键运行整个场景的流程。
• Stoplight：支持直接导入OpenAPI spec，自动生成和Swagger类似的端点文档和调试界面，同时专门提供了「Guides」模块来编写业务场景级的多端点流程，内容和端点可以关联，用户看流程的时候能直接跳转对应端点调试。
• 自定义集成页面：自己搭一个简单的页面，左侧嵌入官方Swagger UI组件（保留所有调试功能），右侧用Markdown或者静态HTML展示业务场景流程。这种方式完全自定义，能完美匹配你的需求，只是需要少量前端开发工作。

内容的提问来源于stack exchange，提问作者Djent