Skip to main content
APIContext
Talk to salesStart free
Start HereGuidesConceptsCLIReferenceChangelog

Manage OpenAPI Specifications

APImetrics evaluates your APIs against the OpenAPI Specification (OAS) documents you provide. The specification you attach to a project defines the contract — the operations, request/response schemas, and server endpoints — that Conformance checks measure your live traffic against. It is also the reference surface used when computing Monitoring Coverage.

This page describes how to upload, select, edit, and remove the OpenAPI specifications a project uses.

Where OpenAPI specifications are managed​

There are two places to add an OpenAPI specification to a project:

  • Conformance Settings — the Manage OpenAPI Specifications section, used to attach the specification that Conformance checks evaluate against.
  • Catalog — upload a specification to compare your intended API surface against observed live traffic. See Catalog for that workflow.

A specification uploaded through either path is stored with the project and can be selected for Conformance checks. You can also upload and view specification files directly from the Files section in the sidebar.

Upload an OpenAPI specification from Conformance Settings​

  1. From the left-hand navigation, select Conformance.
  2. Go to the Settings tab.
  3. Scroll to the Manage OpenAPI Specifications section.
  4. Choose the option to add a specification, then select your JSON or YAML file.
  5. Upload the file. Once processed, the specification appears in the list of specifications available to the project.

If a project has no OpenAPI specification attached, the Conformance Summary page prompts you to upload one before schema conformance can be evaluated.

Select the specification used for conformance​

Once one or more specifications are attached to the project, select the one you want Conformance checks to evaluate against in the Manage OpenAPI Specifications section of Conformance > Settings. APImetrics runs schema conformance and coverage checks against the selected specification.

Edit or remove a specification​

From the Manage OpenAPI Specifications section in Conformance > Settings, you can edit, replace, or delete the specifications attached to a project. Removing the specification that Conformance is currently evaluating against will stop schema and coverage checks until another specification is selected.

How specifications drive coverage gating​

The endpoints defined in your selected OpenAPI specification establish the expected API surface for the project. APImetrics compares the endpoints actually being monitored against that expected surface to compute coverage:

  • Endpoint Coverage is the percentage of the unique server endpoints — identified by method, host, and path — declared in (or observed against) the specification that are currently being monitored.
  • Monitor Coverage is the percentage of the project's configured Monitors that are currently being monitored.

When you enable Coverage Checks and set threshold percentages, Conformance will fail if coverage of the specification's endpoints falls below your thresholds. This is the gating mechanism: an accurate, up-to-date specification is what makes coverage gating meaningful, because the specification defines what "full coverage" means for the project.

For the full coverage configuration workflow — enabling checks, setting thresholds, and discovering your current coverage percentages — see Monitoring Coverage.

Comparing a specification against live traffic​

To compare the endpoints declared in your specification against the endpoints APImetrics observes from live traffic — surfacing drift between the intended and implemented API — upload the specification in the Catalog. The Catalog's OpenAPI Coverage view shows which declared endpoints are being exercised and which observed endpoints are not yet in any specification.