Spec Version + OpenAPI Collector

✓ Guardrail ↓ Collector Beta Devex Build And Ci

Enforce Spec Version using data collected by OpenAPI Collector. Automatically check devex build and ci standards on every PR.

Guardrail: Ensures all REST API specs meet a minimum OpenAPI version. Compares the major version from `.api.spec_files[].version` against `min_version` (default: 3). Flags any spec below the threshold. Only checks entries with `protocol: "rest"`. Skips if no REST spec files were detected.

Data Source: Detect OpenAPI and Swagger spec files in repositories (any version — Swagger 1.x/2.0, OpenAPI 3.0/3.1+). Writes spec metadata to `.api.spec_files[]` and full raw specs to `.api.native.openapi`. Handles both naming conventions in YAML and JSON formats.

Get Started View on GitHub

How OpenAPI Collector Powers This Guardrail

The OpenAPI Collector gathers metadata from your documentation systems. This data flows into Lunar's Component JSON, where the Spec Version guardrail evaluates it against your standards.

When enabled, this check runs automatically on every PR and in AI coding workflows, providing real-time enforcement with actionable feedback.

↓ OpenAPI Collector Gathers Data Collector

Extracts metadata from code, configs, and tool outputs

{ } Component JSON

Data centralized in structured format for evaluation

✓ Spec Version Checks Guardrail

Pass/fail result with actionable feedback in PRs

Quick Start Configuration

Add both the collector and policy to your lunar-config.yml to enable this guardrail.

📄 lunar-config.yml

# Step 1: Enable the OpenAPI Collector
collectors:
  - uses: github://earthly/lunar-lib/collectors/openapi@v1.0.5
    # with: ...

# Step 2: Enable the OpenAPI Guardrails
policies:
  - uses: github://earthly/lunar-lib/policies/openapi@v1.0.5
    include: [spec-version]
    # with: ...

What OpenAPI Collector Collects

This collector gathers the following data that the Spec Version guardrail evaluates.

Collector code

`openapi`

Searches the repository for OpenAPI and Swagger specification files (any version) by common filenames (openapi.yaml, openapi.yml, openapi.json, swagger.yaml, swagger.yml, swagger.json). For each spec found:

Writes spec file metadata to .api.spec_files[] (protocol-agnostic)
Records the declared version (e.g., "2.0", "3.0.3", "3.1.0") so policies can enforce version requirements
Sets has_docs: true — OpenAPI/Swagger specs inherently contain human-readable documentation (descriptions, summaries, examples)
Stores the full raw spec as JSON under .api.native.openapi (all versions share one key — same spec lineage)

Example Data Flow

Here's an example of the data that OpenAPI Collector writes to the Component JSON, which Spec Version then evaluates.

{ } component.json From OpenAPI Collector

{
  "api": {
    "spec_files": [
      {
        "path": "api/openapi.yaml",
        "format": "openapi",
        "protocol": "rest",
        "valid": true,
        "version": "3.0.3",
        "operation_count": 12,
        "schema_count": 5,
        "has_docs": true
      },
      {
        "path": "legacy/swagger.json",
        "format": "swagger",
        "protocol": "rest",
        "valid": true,
        "version": "2.0",
        "operation_count": 8,
        "schema_count": 3,
        "has_docs": true
      }
    ],
    "native": {
      "openapi": {
        "api/openapi.yaml": {
          "openapi": "3.0.3",
          "info": { "title": "User API", "version": "1.0.0" },
          "paths": { "/users": { "get": { "...": "full spec" } } }
        },
        "legacy/swagger.json": {
          "swagger": "2.0",
          "info": { "title": "Petstore", "version": "1.0.0" },
          "paths": { "/pets": { "get": { "...": "full spec" } } }
        }
      }
    }
  }
}

Configuration Options

OpenAPI Collector Inputs

Input	Required	Default	Description
`find_command`	Optional	`find . -type f \( -name 'openapi.yaml' -o -name 'openapi.yml' -o -name 'openapi.json' -o -name 'swagger.yaml' -o -name 'swagger.yml' -o -name 'swagger.json' \) -not -path '/node_modules/' -not -path '/vendor/' -not -path '/.git/'`	Custom find command to locate OpenAPI/Swagger spec files. Default searches for common filenames recursively, excluding node_modules and vendor dirs.

OpenAPI Guardrails Inputs

Input	Required	Default	Description
`min_version`	Optional	`3`	Minimum required major OpenAPI version. Specs with a major version below this value will fail. Default is 3 (i.e., require OpenAPI 3.x+).

Learn More

Guardrail · OpenAPI Guardrails Spec Version View all compatible integrations

→

Collector OpenAPI Collector View full documentation

→

Ready to Automate Your Standards?

See how Lunar can turn your AGENTS.md, engineering wiki, compliance docs, or postmortem action items into automated guardrails with our 100+ built-in guardrails.

Works with any process

AI agent rules & prompt files

Post-mortem action items

Security & compliance policies

Testing & quality requirements

Automate Now

Paste your AGENTS.md or manual process doc and get guardrails in minutes

Book a Demo