Skip to content
EkLine Documentation

Review your OpenAPI spec

Lint your OpenAPI specification with EkLine to catch missing descriptions, security gaps, and unused components before your API docs ship.

Your API reference is only as good as the OpenAPI specification behind it. When operations lack descriptions or schemas omit constraints, the rendered docs leave developers guessing. EkLine reviews your OpenAPI spec the same way it reviews prose — flagging issues before they reach your published reference.

This guide shows you how to point EkLine at an OpenAPI spec, read the results, and add the check to your pipeline.

Goal

Section titled “Goal”

Run an EkLine review against an OpenAPI specification file and fix the issues it reports.

What EkLine checks

Section titled “What EkLine checks”

EkLine analyzes the structure and content of your spec, not just its syntax. A review covers three areas:

AreaWhat EkLine looks for
DescriptionsEvery operation (a path plus method, such as GET /users) and every reusable component has a clear, meaningful description. EkLine flags generic or empty descriptions.
Security best practicesString properties define a maxLength and a format, pattern, enum, or const. Arrays define maxItems. Integers define a format and minimum/maximum. These constraints help prevent oversized or malformed payloads.
StructureThe spec contains no unused components, no broken references, and no executable code inside Markdown descriptions.

Prerequisites

Section titled “Prerequisites”

Before you start, make sure you have:

  • The EkLine CLI installed. See the CLI guide to download the binary.
  • Your EkLine token. Get it from Settings > Organization > Access in the EkLine Dashboard.
  • An OpenAPI specification file in JSON (.json) or YAML (.yaml, .yml) format. EkLine supports OpenAPI 2.0, 3.0, and 3.1.

Steps

Section titled “Steps”

  1. Point EkLine at your spec.

    Add the openapiSpec option to your ekline.config.json, or pass the --openapi-spec flag when you run the CLI.

    ekline.config.json
    {
      "contentDirectory": ["docs"],
      "openapiSpec": "openapi.yaml"
    }

  2. Run the review.

    Terminal window
    ekline-cli --ek-token YOUR_TOKEN

    EkLine reviews your documentation directories and your OpenAPI spec in the same run. Results print to the terminal by default.

  3. Read the results.

    Each issue names the location in your spec and explains the problem. For example, an operation without a description reports:

    openapi.yaml:42 Operation "GET /users" is missing a description.

  4. Fix an issue.

    Add the missing detail to your spec. For the example above, give the operation a description that explains what it does:

    openapi.yaml
    paths:
      /users:
        get:
          summary: List users
          description: Returns a paginated list of active users in your organization.
          responses:
            '200':
              description: A list of users.

  5. Re-run the review to confirm the fix.

    Terminal window
    ekline-cli --ek-token YOUR_TOKEN

    The issue you fixed no longer appears, and the total issue count drops.

Verification

Section titled “Verification”

Your review is working when EkLine reports issues that reference your spec file by name and line, such as openapi.yaml:42. After you add the missing descriptions and constraints, re-run the review and confirm the count decreases.

Add the review to your pipeline

Section titled “Add the review to your pipeline”

To catch spec issues on every change, run the same CLI command in CI. Store your token as a pipeline secret and keep the openapiSpec value in your committed ekline.config.json so every run uses it.

Terminal window
ekline-cli --ek-token "$EK_TOKEN"

For a complete pipeline setup, see the GitHub Action quickstart.

Troubleshooting

Section titled “Troubleshooting”

Invalid file type

Section titled “Invalid file type”

EkLine accepts only .json, .yaml, and .yml specs. Confirm your file uses one of these extensions.

File too large

Section titled “File too large”

A spec must be 10 MB or smaller. Split a large spec into multiple files, or remove unused components to reduce its size.

Spec fails to parse

Section titled “Spec fails to parse”

If EkLine reports that your spec is invalid, the file does not match the OpenAPI structure. Validate it against the OpenAPI 2.0, 3.0, or 3.1 schema and fix any structural errors before reviewing.

Spec is not reviewed

Section titled “Spec is not reviewed”

If you use changedFiles or a pull request workflow, EkLine reviews the spec only when the spec file changes. Edit the spec, or run the CLI without the changed-files option to force a full review.

Too many findings to address at once

Section titled “Too many findings to address at once”

Disable a rule you don’t need across the whole project with the ignore option, or document an intentional exception inline. See Ignoring rules.

Next steps

Section titled “Next steps”