wework/speccy

OpenAPI质量规则检查镜像

镜像概述

该Docker镜像专为OpenAPI 3.0.x规范文件提供自动化质量规则检查功能，通过强制执行预设或自定义规则集，确保API文档的语法正确性、规范一致性和最佳实践符合性，帮助开发团队在API开发流程中维护高质量的接口文档。

核心功能与特性

• 版本支持：专门针对OpenAPI 3.0.x规范版本进行优化
• 规则检查：内置多维度质量规则，包括语法验证、结构完整性、最佳实践和安全建议
• 自定义规则：支持导入外部规则集文件，满足特定项目或组织的定制化需求
• 多格式输出：提供文本、JSON、HTML等多种检查结果输出格式，便于集成和查看
• 轻量集成：容器化设计，可无缝集成到CI/CD流水线或本地开发环境

使用场景与适用范围

• API文档开发阶段的本地质量验证
• CI/CD流程中的自动化质量门禁（提交/合并前检查）
• 团队协作中统一API文档规范执行
• API文档评审前的自动化预检
• 开源项目的API规范质量保障

使用方法与配置说明

基本使用（docker run）

bash
docker run --rm -v /本地路径/openapi.yaml:/app/spec.yaml 镜像名称 /app/spec.yaml

说明：将本地OpenAPI规范文件挂载到容器内/app/spec.yaml路径，镜像会对该文件执行默认规则检查并输出结果。

自定义规则集

通过挂载规则集文件并指定环境变量使用自定义规则：

bash
docker run --rm \
  -v /本地路径/openapi.yaml:/app/spec.yaml \
  -v /本地路径/custom-rules.json:/app/rules.json \
  -e RULESET=/app/rules.json \
  镜像名称 /app/spec.yaml

输出格式配置

通过OUTPUT_FORMAT环境变量指定输出格式：

bash
# JSON格式输出到文件
docker run --rm \
  -v /本地路径/openapi.yaml:/app/spec.yaml \
  -e OUTPUT_FORMAT=json \
  镜像名称 /app/spec.yaml > results.json

# HTML格式输出
docker run --rm \
  -v /本地路径/openapi.yaml:/app/spec.yaml \
  -e OUTPUT_FORMAT=html \
  镜像名称 /app/spec.yaml > report.html

docker-compose配置示例

yaml
version: '3.8'
services:
  openapi-quality:
    image: 镜像名称
    volumes:
      - ./openapi-specs:/app/specs  # 挂载规范文件目录
      - ./custom-rules:/app/rules  # 挂载规则集目录
      - ./reports:/app/reports     # 挂载报告输出目录
    environment:
      - RULESET=/app/rules/company-rules.json
      - OUTPUT_FORMAT=html
      - STRICT_MODE=true  # 违反规则时返回非零退出码
    command: /app/specs/api-v1.yaml > /app/reports/v1-quality.html

配置参数说明