OpenAPI Guardrails

✓ Policy Beta Devex Build And Ci

Enforce OpenAPI-specific standards. Validates spec version meets a configurable minimum (default: 3). Operates on `.api.spec_files[]` entries with `protocol: "rest"` and `.api.native.openapi` for deep spec inspection.

Add openapi to your lunar-config.yml:

uses: github://earthly/lunar-lib/policies/openapi@v1.0.0

Get Started View on GitHub

Included Guardrails

This policy includes 1 guardrail that enforce standards for your devex build and ci.

Guardrail

`spec-version`

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.

openapi swagger api version migration

View Guardrail

How Guardrails Fit into Lunar

Lunar guardrails define your engineering standards as code. They evaluate data collected by integrations and produce pass/fail checks with actionable feedback.

Policies support gradual enforcement—from silent scoring to blocking PRs or deployments—letting you roll out standards at your own pace without disrupting existing workflows.

Learn How Lunar Works →

↓ Integrations Gather Data

Collectors extract metadata from code, CI pipelines, tool outputs, and scans

{ } Centralized as JSON

All data merged into each component's unified metadata document

✓ Guardrails Enforce Standards This Policy

Real-time feedback in PRs and AI workflows

Example Evaluated Data

This policy evaluates structured metadata from the Component JSON. Here's an example of the data it checks:

{ } component.json Example Input

{
  "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": { "...": "full raw spec" }
        },
        "legacy/swagger.json": {
          "swagger": "2.0",
          "info": { "title": "Petstore", "version": "1.0.0" },
          "paths": { "...": "full raw spec" }
        }
      }
    }
  }
}

Required Integrations

This policy evaluates data gathered by one or more of the following integration(s). Make sure to enable them in your lunar-config.yml.

Collector Documentation Required

OpenAPI Collector

Collects OpenAPI and Swagger spec metadata and raw specs

Configuration

Configure this policy in your lunar-config.yml.

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+).

Documentation

View on GitHub

OpenAPI Guardrails

Enforce OpenAPI and Swagger specification standards for REST APIs.

Overview

OpenAPI-specific policy checks that operate on .api.spec_files[] entries with protocol: "rest". For protocol-agnostic checks (spec exists, spec valid, has docs), see the api-docs policy.

Policies

Policy	Description
`spec-version`	Ensures all REST specs meet a minimum OpenAPI version (default: 3), flags older specs

Required Data

This policy reads from the following Component JSON paths:

Path	Type	Provided By
`.api.spec_files[]`	array	`openapi` collector
`.api.spec_files[].version`	string	`openapi` collector
`.api.spec_files[].protocol`	string	`openapi` collector

Installation

Add to your lunar-config.yml:

policies:
  - uses: github://earthly/lunar-lib/policies/openapi@main
    on: ["domain:your-domain"]
    enforcement: report-pr
    # with:
    #   min_version: "3"  # default — require OpenAPI 3.x+

Requires the openapi collector to be enabled.

Examples

Passing Example

Repository with OpenAPI 3.x spec:

{
  "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
      }
    ]
  }
}

Failing Example — Swagger 2.0

{
  "api": {
    "spec_files": [
      {
        "path": "swagger.json",
        "format": "swagger",
        "protocol": "rest",
        "valid": true,
        "version": "2.0",
        "operation_count": 8,
        "schema_count": 3,
        "has_docs": true
      }
    ]
  }
}

Failure message: "swagger.json uses version 2.0 — minimum required is 3"

Remediation

spec-version

Migrate from Swagger 2.0 to OpenAPI 3.x using a tool like swagger2openapi
Key changes: host/basePath → servers[], definitions → components/schemas, produces/consumes → per-operation content types
Validate the migrated spec with Spectral

Open Source

This policy is open source and available on GitHub. Contribute improvements, report issues, or fork it for your own use.

View Repository

Common Use Cases

Explore how individual guardrails work with specific integrations.

Spec Version + OpenAPI Collector Ensures all REST API specs meet a minimum OpenAPI version. Compares the major...

→

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