# Review your OpenAPI spec

import { Aside, Steps, Tabs, TabItem } from '@astrojs/starlight/components';

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

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

## What EkLine checks

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

| Area | What EkLine looks for |
|------|------------------------|
| Descriptions | Every 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 practices | String 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. |
| Structure | The spec contains no unused components, no broken references, and no executable code inside Markdown descriptions. |

<Aside type="note">
EkLine reviews the spec file itself. It does not compare your spec against your prose documentation.
</Aside>

## Prerequisites

Before you start, make sure you have:

- The EkLine CLI installed. See [the CLI guide](/reviewer/integrations/cli-integration/) to download the binary.
- Your EkLine token. Get it from **Settings > Organization > Access** in the [EkLine Dashboard](https://ekline.io/dashboard).
- An OpenAPI specification file in JSON (`.json`) or YAML (`.yaml`, `.yml`) format. EkLine supports OpenAPI 2.0, 3.0, and 3.1.

## Steps

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

   <Tabs>
     <TabItem label="Config file">
       ```json title="ekline.config.json"
       {
         "contentDirectory": ["docs"],
         "openapiSpec": "openapi.yaml"
       }
       ```
     </TabItem>
     <TabItem label="CLI flag">
       ```bash
       ekline-cli --ek-token YOUR_TOKEN --content-directory ./docs --openapi-spec openapi.yaml
       ```

       The `--openapi-spec` flag also accepts the short form `-oas`.
     </TabItem>
   </Tabs>

2. **Run the review.**

   ```bash
   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:

   ```yaml title="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.**

   ```bash
   ekline-cli --ek-token YOUR_TOKEN
   ```

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

</Steps>

## 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

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.

```bash
ekline-cli --ek-token "$EK_TOKEN"
```

For a complete pipeline setup, see the [GitHub Action quickstart](/reviewer/quickstart/github-action/).

<Aside type="tip">
In a pull request workflow, EkLine reviews your spec when the spec file is among the changed files. This keeps reviews fast on large repositories.
</Aside>

## Troubleshooting

### Invalid file type

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

### 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

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

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

Disable a rule you don't need across the whole project with the `ignore` option, or document an intentional exception inline. See [Ignoring rules](/reviewer/configuration/ignoring-rules).

## Next steps

- [Ignoring rules](/reviewer/configuration/ignoring-rules) — Handle false positives and intentional exceptions.
- [CLI reference](/reviewer/integrations/cli-integration/) — All configuration options and flags.
- [Framework support](/reviewer/configuration/framework-support) — Improve checks for MDX-based docs.