Spec Valid + OpenAPI Collector

✓ Guardrail ↓ Collector Beta Repository And Ownership

Enforce Spec Valid using data collected by OpenAPI Collector. Automatically check repository and ownership standards on every PR.

Guardrail: Checks that all detected API spec files parse without errors by verifying `.api.spec_files[].valid` is true for every entry. Skips if no 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 Valid 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 Valid 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.0
    # with: ...

# Step 2: Enable the API Docs Guardrails
policies:
  - uses: github://earthly/lunar-lib/policies/api-docs@v1.0.0
    include: [spec-valid]
    # with: ...

What OpenAPI Collector Collects

This collector gathers the following data that the Spec Valid 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 Valid 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.

API Docs Guardrails Inputs

Input	Required	Default	Description

Learn More

Guardrail · API Docs Guardrails Spec Valid View all compatible integrations

→

Collector OpenAPI Collector View full documentation

→

Ready to Automate Your Standards?

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

Works with any process

Infrastructure conventions

Post-mortem action items

Security & compliance policies

Testing & quality requirements

Automate Now

Turn any process doc into guardrails

Book a Demo