OpenAPI Collector
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.
openapi to your lunar-config.yml:uses: github://earthly/lunar-lib/collectors/openapi@v1.0.0
What This Integration Collects
This integration includes 1 collector that gather metadata from your systems.
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)
How Collectors Fit into Lunar
Lunar watches your code and CI/CD systems to collect SDLC data from config files, test results, IaC, deployment configurations, security scans, and more.
Collectors are the automatic data-gathering layer. They extract structured metadata from your repositories and pipelines, feeding it into Lunar's centralized database where guardrails evaluate it to enforce your engineering standards.
Learn How Lunar Works →Example Collected Data
This collector writes structured metadata to the Component JSON. Here's an example of the data it produces:
{
"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
Configure this collector in your lunar-config.yml.
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. |
Documentation
View on GitHubOpenAPI Collector
Detect and analyze OpenAPI and Swagger specification files in repositories (any version).
Overview
Searches repositories for OpenAPI and Swagger specification files by common filenames and parses their contents. Stores the full raw spec under .api.native.openapi for deep inspection, and writes protocol-agnostic metadata to .api.spec_files[]. Supports both YAML and JSON formats. OpenAPI is the evolution of the Swagger specification — Swagger 2.0 was renamed to OpenAPI 3.0 when donated to the OpenAPI Initiative. This collector handles both naming conventions (openapi.yaml/openapi.json and swagger.yaml/swagger.json) in a single pass.
Collected Data
This collector writes to the following Component JSON paths:
Protocol-Agnostic (.api.spec_files[])
| Path | Type | Description |
|---|---|---|
.api.spec_files[] |
array | Spec file metadata (one entry per spec file found) |
.api.spec_files[].path |
string | File path relative to repo root |
.api.spec_files[].format |
string | "openapi" for OpenAPI 3.x+, "swagger" for Swagger 1.x/2.0 |
.api.spec_files[].protocol |
string | Always "rest" |
.api.spec_files[].valid |
boolean | Whether the file parses without errors |
.api.spec_files[].version |
string | Spec version (e.g. "3.0.3", "3.1.0", "2.0") |
.api.spec_files[].operation_count |
number | Number of operations (path + method combinations) |
.api.spec_files[].schema_count |
number | Number of schema/definition entries |
.api.spec_files[].has_docs |
boolean | Always true for OpenAPI/Swagger — these specs inherently contain human-readable documentation |
Native/Raw (.api.native.openapi)
| Path | Type | Description |
|---|---|---|
.api.native.openapi |
object | Map of file path → raw spec as JSON. All versions live here (same spec lineage) |
File patterns: OpenAPI 3.x (openapi.yaml, openapi.yml, openapi.json) and Swagger 2.0 (swagger.yaml, swagger.yml, swagger.json).
Collectors
| Collector | Description |
|---|---|
openapi |
Detects OpenAPI and Swagger spec files (any version), extracts metadata and raw specs |
Installation
Add to your lunar-config.yml:
collectors:
- uses: github://earthly/lunar-lib/collectors/openapi@main
on: ["domain:your-domain"]
# with:
# find_command: "find . -name 'openapi.yaml' -not -path '*/node_modules/*'"
Open Source
This collector is open source and available on GitHub. Contribute improvements, report issues, or fork it for your own use.
Common Use Cases
Explore guardrails that use data from OpenAPI Collector.
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.
Infrastructure conventions
Post-mortem action items
Security & compliance policies
Testing & quality requirements