Improving OpenAPI Specifications with the Spectral API Linter

Jan 29, 25

When developing modern APIs, OpenAPI specifications have become the de-facto standard for describing endpoints, payloads, and behavior. But while OpenAPI makes APIs easier to share and understand, it also comes with a challenge: how do we ensure that specifications are consistent, maintainable, and free of errors?

That’s where linters come in. Just as code linters catch mistakes in programming languages, OpenAPI linters like Spectral apply rules to check and improve API specifications.

In my bachelor thesis, I set out to evaluate which linter rules actually matter in practice—and how they can improve API quality without overwhelming developers.

Why Linter Rules Matter

APIs often evolve quickly, and specifications can become inconsistent or ambiguous. For example:

  • Different naming conventions across endpoints
  • Missing or unclear schema descriptions
  • Overly complex parameter structures

These issues may not break an API immediately, but they reduce clarity, increase onboarding time, and can introduce hidden bugs.

Linters help by enforcing best practices. However, existing rule sets are often too generic or not tailored to real-world needs. My thesis explored how to refine these rules to maximize value for developers.

Research Approach

I conducted a practical evaluation of linter rules in Spectral, combining:

  • Rule analysis: reviewing existing Spectral rules and categorizing them.
  • Real World Analysis: applying rules to real OpenAPI specs to see their impact.

This mix of theoretical and empirical research allowed me to identify rules that balance helpfulness with usability.

Key Findings

  • Most Real World APIs are violating some rules: Rarely any OpenAPI sepcification from the large high quality dataset was 100% compliant to the default ruleset.
  • Not every rule is critical for spec quality: Rules can clearly be separated into low impact and high impact rules judging by real world compliance.
  • Balance is key: Too many strict rules might lead to frustration. A carefully curated rule set worked better than applying everything at once.

In short: a focused, developer-friendly set of rules adds real value, while overly rigid configurations discourage adoption.

Outlook

The thesis concludes that Spectral’s default OpenAPI ruleset is classifies its rule severity not accordingly to real world needs. This thesis provides a data driven approach helping developers understand the real world impact of linter errors on their specification quality.

Final Thoughts

Linters won’t replace good API design practices, but they are a powerful tool to support consistency and quality. This thesis tries to help developers find the right balance of reusing default rules targeted to the OpenAPI Specification and building own rulesets for their specific needs.

Read the whole thesis

If you are interested in reading the whole thesis, or you are interested in how I set up my data analysis pipeline and the LaTeX project repository feel free to take a look here: github.com/paulbrenker/thesis