Optic Compared to Spectral

Spectral (opens in a new tab) and Optic (opens in a new tab) are both open source CLIs that lint OpenAPI/Swagger specifications. Both tools will ensure the spec you give it is a valid OpenAPI/Swagger document, and can apply additional validation that the APIs described follow certain design conventions.

How Spectral works:

spectral lint openapi.yml

Spectral loads an OpenAPI specification into memory and then applies rules (defined in YAML or JS) to specific JSON Paths in your specification. For instance you could apply a rule to all tags using this JSON Path $.tags[*]. If any of your rules do not pass, Spectral will give you a list of errors and warnings until you fix them

This works great when you’re designing a brand new API, but if your API has already been published, Spectral may not be the best fit. Your legacy APIs and already published operations probably don’t follow your latest API standards — and they probably never will. Getting your the Spectral rules to pass for these existing endpoints would require making a lot of breaking changes. Most teams end up with a lot of warning and errors they never fix and have to turn off rules.

How Optic works:

optic diff develop:openapi.yml latest:openapi.yml

Optic is the first API linter built with the API lifecycle in-mind. When testing your API design, it always considers two versions of your API, for example: the version on the develop vs the latest release tag. This lets Optic check for all kinds of things Spectral misses like breaking changes and proper use of your API versioning scheme.

Because Optic understands API change, it can apply your latest API standards to new API endpoints, and a looser set of standards to legacy endpoints that can’t change. We call this “Forwards-only governance” — Teams like Snyk use this approach to govern all their APIs (opens in a new tab). With Optic, developers only get actionable feedback from the tool and they don’t have to turn rules off to get CI to pass.

Custom rules are also supported. You can test your API changes with nice handlers:

response.property.changed((before, after) => {
  if (before.required && !after.required) 
      throw new Error("Making a response property optional is a breaking change")
})

If you already have custom Spectral rules, don’t worry, Optic can run them out of the box. Because Spectral is also open source, Optic uses its runtime to call your existing rulesets. You can even tap into Optic’s superpowers by running some of your rules on added operations and a looser set of rules to all the existing operations. It’s effective API governance, that does not get in the way.

 ruleset:
	- spectral:
      # These rules will ony run on things you add to your API
      # Ie new properties, operations, responses, etc.
      added:
        # URLs are supported
        - https://www.apistyleguides.dev/api/url-style-guides/3ba0b4a
        # Local files work too.
      # - ./local-file.js
      # These rules will ony run on everything in the spec (normal spectral)
      always:
        - https://www.apistyleguides.dev/api/url-style-guides/3ba0b4a
	

What kinds of Rules can you write with Optic?

Because Optic allows you to run your Spectral rules, it can do everything Spectral can do and a whole lot more.

Sound interesting to you? Try it today or set up a call with Optic’s API Experts to talk about your team’s approach to API Governance

"To deliver a high quality API we need to be working API-first, and keeping track of the promises we have made to consumers. API-first has always been hard, Optic is the first tool we have found that makes it easy to quickly build and safety extend our APIs. "

Kostas Petrakis Lead API Engineer