API Design Linter and Playground for OpenAPI Specifications

Problem

API design mistakes are cheap to fix before an endpoint ships and expensive afterwards, because clients start depending on them. Style guides exist, but nobody reads a thirty-page document during a pull request. Existing linters such as Spectral report a rule name and a line number. They rarely explain why the rule exists, which is what a junior developer needs in order to stop making the mistake.

This is different from the API Contract Checker idea in this library, which compares two versions of an API to find breaking changes. This project checks the design of a single API against a written standard.

What you build

• A parser for OpenAPI 3.0 and 3.1 in YAML or JSON that keeps line and column positions, so findings point to the exact place in the file.
• A rule engine where each rule is a small, tested function with an id, a severity, a message, an explanation, a documentation link and a before and after example.
• A default style guide of at least 25 rules, for example:
  • Status codes: creation returns 201 with a Location header, deletion returns 204 with no body, every operation documents its 4xx responses, and no error is returned with 200.
  • Errors: one error shape across the API, ideally Problem Details as defined in RFC 9457.
  • Pagination: every list endpoint is paginated, with the same parameter names and response fields everywhere.
  • Versioning: one strategy used consistently, in the path or in a header.
  • Naming: plural resource nouns and consistent casing for paths, parameters and fields.
  • Safety: security schemes defined and applied, and endpoints that create payments or orders accept an idempotency key.
• A web playground: paste or upload a specification, see findings inline next to the source, and open a finding to read its explanation.
• A command line tool with configurable rules and a CI mode that fails on errors.

Suggested architecture

• TypeScript for the engine, so the same code runs in the command line tool and in the browser. Use a YAML parser that preserves positions and a JSON Schema validator for structure, and write the rule engine yourself.
• A code editor component such as CodeMirror or Monaco for the playground.
• Rules as plain modules, each with unit tests built from small specification fragments that should pass and fail.

Milestones by month

1. Month 1: parser with positions, rule engine, first ten rules with tests, command line output.
2. Month 2: remaining rules, explanations and documentation pages, configuration file.
3. Month 3: web playground, CI mode, a GitHub Action.
4. Month 4: evaluation on public specifications and with developers, report and demo.

How it will be assessed

• Results from running the linter over at least 30 public OpenAPI descriptions: the most common findings, false positives found by hand review, and runtime per specification.
• A comparison with Spectral's built-in OpenAPI ruleset on the same specifications: overlap, rules only you have, and rules only Spectral has.
• A study with at least eight student developers, each fixing one flawed specification with rule names only and another with your explanations, measuring time and correctness.
• Test coverage of the rule engine.

Pitfalls

• Presenting opinions as facts. Where reasonable teams disagree, such as path versioning against header versioning, make the rule configurable and say so in the explanation.
• Treating OpenAPI 3.0 and 3.1 as identical. Their schema handling differs.
• Losing line numbers after resolving $ref references, which makes findings impossible to locate.
• Explanations that turn into essays. Two or three sentences and an example are enough.