如何在OpenAPI/Swagger中外置冗长代码示例并引用？

当然可以把冗长的代码示例外置，下面给你几种可行的方案：

• 预处理+Components定义复用示例
  先在Swagger的components/examples里把代码示例定义成独立条目：

  components:
    examples:
      phpMyApiExample:
        value: |
          <?php
          // 你的超长PHP代码示例...
  

  然后在description里用自定义占位符，比如：

  description: |
    PHP示例代码
    {{phpMyApiExample}}
  

  最后写个简单脚本（比如Python/Node.js），把占位符替换成带Markdown代码块格式的内容，生成最终可用的Swagger文档。

• 单独文件存代码+脚本注入
  把每个冗长的代码示例存成单独的文件，比如my-api-php-example.php。
  在Swagger的description里留标记：

  description: |
    PHP示例代码
    [PHP_EXAMPLE]
  

  再用脚本读取Swagger文件和代码文件，把标记替换成Markdown代码块格式（php\n{文件内容}\），输出处理后的yaml文件。

• Swagger UI自定义插件加载
  如果只是在Swagger UI展示时需要加载外部代码，可以写个Swagger UI插件。识别description里的特定标记（比如@example: php/my-api-example），在文档加载时从指定路径读取代码文件，自动替换成Markdown代码块显示。

注意：原生OpenAPI规范不支持直接在description的Markdown里引用外部内容，所以必须借助预处理脚本或者UI层的自定义逻辑来实现。

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