寻求可解析Swagger文件并在UI中动态生成代码示例的工具

我来帮你梳理几个能实现需求的方案，刚好之前做API文档相关的工作时研究过类似场景😉

1. 别忽略Swagger-UI本身的能力！ #

你可能没注意到，Swagger-UI原生支持动态生成代码示例，完全符合你的需求：

• 默认情况下，Swagger-UI会根据你的API定义自动生成多种语言（比如PHP、Python、JavaScript等）的代码调用示例，在每个API的"Try it out"区域旁边就能切换查看；
• 如果需要自定义代码示例格式，可以在你的Swagger/YAML文件里通过x-code-samples扩展字段手动添加，比如：

  paths:
    /user/events:
      get:
        x-code-samples:
          - lang: PHP
            source: |
              <?php
              $client = new GuzzleHttp\Client();
              $response = $client->request('GET', 'http://api.rakam.io/user/events', [
                'headers' => [
                  'Authorization' => 'Bearer YOUR_TOKEN',
                ],
              ]);
              echo $response->getBody();
              ?>
  

• 你可以把Swagger-UI嵌入到自己的UI系统里，通过配置项调整样式和功能，完全不用切换到其他工具。

2. 重新利用OpenAPI Generator（原Swagger Codegen） #

你提到用codegen在GitHub生成了代码示例，但不知道怎么动态展示，其实有两种思路：

• 生成带代码示例的静态文档：用OpenAPI Generator的html2模板生成完整的API文档站点，里面包含自动生成的代码示例，直接把这个站点嵌入到你的UI里（比如用iframe），或者把生成的HTML片段整合到你的页面中；
• 动态获取代码片段：用codegen的CLI命令批量生成指定语言的代码示例文件，然后在你的后端写个接口读取这些文件内容，前端调用接口获取后渲染成代码块。比如生成PHP示例的命令：

  openapi-generator generate -i your-swagger.yaml -g php -o ./api-samples/php --skip-validate-spec
  

3. 第三方工具推荐 #

如果Swagger-UI和codegen的能力还不够，这些工具能帮到你：

• Redoc：一款现代的OpenAPI文档渲染工具，支持自动生成多语言代码示例，界面美观且支持自定义主题，完全兼容Swagger规范。你可以把Redoc嵌入到自己的UI中，或者用它的React组件直接集成，代码示例是动态切换的，效果和你提到的目标站点非常接近；
• Stoplight Studio：不仅能编辑OpenAPI文档，还能生成带交互式代码示例的文档站点，支持自定义代码模板。你可以用它生成的文档嵌入UI，或者调用它的API获取代码示例数据自己渲染；
• Postman：虽然是测试工具，但Postman可以导入Swagger文件，生成几十种语言的代码片段。你可以通过Postman的API获取这些示例，集成到你的UI里。

4. 手动编写的场景 #

如果你的需求是高度定制化的代码示例（比如要贴合业务场景的特殊逻辑），那可能需要手动编写，但大部分通用场景下，上面的工具已经足够覆盖，没必要重复造轮子。

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