Amalgamated OpenAPI Specs 镜像文档

概述

Amalgamated OpenAPI Specs 是一款专注于合并和管理 OpenAPI 规范的 Docker 镜像。该镜像旨在解决多团队或多模块 API 开发中规范分散的问题，通过集中处理多个 OpenAPI 规范文件，生成统一的规范输出，简化 API 文档维护、接口测试及服务集成流程。

核心功能与特性

核心功能

• 多文件合并：支持将分散的 OpenAPI 规范文件（如路径定义、组件定义、响应模型等）合并为单一规范文件
• 版本兼容：兼容 OpenAPI 2.0（Swagger）及 3.x 版本规范文件的合并处理
• 规范校验：内置规范校验机制，确保合并后的输出符合 OpenAPI 语法标准
• 灵活输出：支持 JSON 或 YAML 格式输出，可自定义输出文件路径

特性

• 轻量级设计：基于 Alpine 基础镜像构建，体积小，启动速度快
• 无状态运行：通过挂载卷实现数据持久化，支持临时或长期运行模式
• 环境变量配置：支持通过环境变量快速配置输入输出路径及合并规则
• 日志输出：提供详细合并过程日志，便于问题排查

使用场景与适用范围

适用场景

• 多团队协作：API 开发团队分散维护不同模块的规范文件，需统一对外提供文档
• 微服务架构：微服务拆分后，各服务独立维护 API 规范，需汇总为整体 API 文档
• 自动化流程：与 CI/CD 流水线集成，实现规范文件变更后的自动合并与文档更新
• API 文档工具集成：作为前置处理步骤，为 Swagger UI、ReDoc 等文档工具提供统一规范输入

适用范围

• API 开发团队
• 微服务架构项目
• 需要集中管理接口规范的企业或组织
• 自动化 API 文档生成与维护场景

使用方法与配置说明

基础使用流程

1. 准备 OpenAPI 规范文件
   将分散的 OpenAPI 规范文件（.json 或 .yaml）存放于本地目录（如 /path/to/local/specs）

2. 运行容器
   通过 docker run 命令启动容器，挂载本地规范文件目录，并配置必要参数：

docker run -d \
  --name amalgamated-openapi \
  -v /path/to/local/specs:/specs \  # 挂载本地规范文件目录到容器内/specs
  -e INPUT_DIR=/specs \             # 指定容器内输入目录（默认：/specs）
  -e OUTPUT_FILE=/specs/merged.yaml \  # 指定合并后输出文件路径（默认：/specs/merged.yaml）
  -e OPENAPI_VERSION=3.0 \          # 目标 OpenAPI 版本（支持 2.0/3.0/3.1，默认：3.0）
  amalgamated-openapi-specs

3. 获取合并结果
   合并后的规范文件将生成在本地挂载目录下（如 /path/to/local/specs/merged.yaml）

配置参数说明

环境变量

合并策略说明

• deep_merge：深度合并，合并所有文件中的路径、组件、参数等，冲突时保留最后读取的文件内容
• override：覆盖合并，以最后读取的文件内容完全覆盖同名节点（适用于主文件+补充文件场景）

高级使用示例

与 Docker Compose 集成

创建 docker-compose.yml 文件：

version: '3'
services:
  openapi-merger:
    image: amalgamated-openapi-specs
    volumes:
      - ./local-specs:/specs
    environment:
      - INPUT_DIR=/specs
      - OUTPUT_FILE=/specs/merged.json
      - OPENAPI_VERSION=3.1
      - MERGE_STRATEGY=deep_merge
    restart: on-failure  # 合并失败时自动重试

启动服务：

docker-compose up

批量处理与过滤

通过挂载包含 .mergeignore 文件的目录，可排除无需合并的文件（语法同 .gitignore）：

# /path/to/local/specs/.mergeignore
*.tmp.yaml  # 排除临时文件
draft/      # 排除草稿目录

注意事项

• 确保挂载的本地目录具有读写权限，避免容器无法读取输入文件或写入输出结果
• 不同版本的 OpenAPI 规范文件合并时，建议统一目标版本（通过 OPENAPI_VERSION 指定）
• 复杂规范文件合并前，建议通过 OpenAPI 在线校验工具 验证单个文件合法性，减少合并错误