This package has been deprecated

Author message:

Spectral's latest version is now available as @stoplight/spectral-cli on npm

@stoplight/spectral

6.5.0 • Public • Published

Demo of Spectral linting an OpenAPI document from the CLI CircleCI NPM Downloads Stoplight Forest

  • Custom Rulesets: Create custom rules to lint JSON or YAML objects
  • Ready-to-use Rulesets: Validate and lint OpenAPI v2 & v3.x and AsyncAPI Documents
  • API Style Guides: Automated API Style Guides using rulesets improve consistency across all your APIs
  • Ready-to-use Functions: Built-in set of functions to help create custom rules. Functions include pattern checks, parameter checks, alphabetical ordering, a specified number of characters, provided keys are present in an object, etc.
  • Custom Functions: Create custom functions for advanced use cases

Overview

🧰 Installation

The easiest way to install spectral is to use either npm:

npm install -g @stoplight/spectral-cli

Or yarn:

yarn global add @stoplight/spectral-cli

You can find more installation methods here.

💻 Usage

1. Create a local ruleset

Spectral, being a generic YAML/JSON linter, needs a ruleset to lint files. A ruleset is a JSON, YAML, or JavaScript/TypeScript file (often the file will be called .spectral.yaml for a YAML ruleset) that contains a collection of rules, which can be used to lint other JSON or YAML files such as an API description.

To get started, run this command in your terminal to create a .spectral.yaml file that will use Spectral's predefined rulesets based on OpenAPI or AsyncAPI:

echo 'extends: ["spectral:oas", "spectral:asyncapi"]' > .spectral.yaml

If you would like to create your own rules, check out the Custom Rulesets page.

2. Lint

Use this command if you have a ruleset file in the same directory as the documents you are linting:

spectral lint myapifile.yaml

Use this command to lint with a custom ruleset, or one that's located in a different directory than the documents being linted:

spectral lint myapifile.yaml --ruleset myruleset.yaml

📖 Documentation

Once you've had a look through the getting started material, some of these guides can help you become a power user.

  • Different Workflows - When and where should you use Spectral? Editors, Git-hooks, Continuous Integration, GitHub Actions, wherever you like!
  • Using the command-line interface - Quickest way to get going with Spectral is in the CLI.
  • Using the JavaScript API - Access the raw power of Spectral via the JS, or hey, TypeScript if you want.
  • Custom Rulesets - Need something more than the core rulesets provide? Fancy building your own API Style Guide? Learn how to create a custom ruleset.
  • Custom Functions - Handle more advanced rules, by writing a little JavaScript/TypeScript and calling it as a function.

ℹ️ Support

If you need help using Spectral or have any questions, please use GitHub Discussions, or visit the Stoplight Community Discord. These communities are a great place to share your rulesets, or show off tools that leverage Spectral.

If you have a bug or feature request, please create an issue.

🌎 Real-World Rulesets

  • Adidas - Adidas were one of the first companies to release their API Style Guide in a written guide and a Spectral ruleset. Lots of good rules to try in here.
  • APIs You Won't Hate - An opinionated collection of rules based on advice in the APIs You Won't Hate community.
  • Azure - Ruleset and complimentary style guide for creating OpenAPI 2 or 3 definitions of Azure services.
  • Box - Lots of Custom Functions being used to enforce good practices that the Box API governance folks are interested in.
  • DigitalOcean - Keeping their OpenAPI nice and tidy, enforcing use of $ref (probably to minimize conflicts), naming conventions for Operation IDs, and all sorts of other handy OpenAPI tips.
  • Tranascom - Don't even think about using anything other than application/json.

Here are more real-world examples of Spectral in action.

⚙️ Integrations

🏁 Help Others Utilize Spectral

If you're using Spectral for an interesting use case, contact us for a case study. We'll add it to a list here. Spread the goodness 🎉

👏 Contributing

If you are interested in contributing to Spectral, check out CONTRIBUTING.md.

🎉 Thanks

📜 License

Spectral is 100% free and open-source, under Apache License 2.0.

🌲 Sponsor Spectral by Planting a Tree

If you would like to thank us for creating Spectral, we ask that you buy the world a tree.

Package Sidebar

Install

npm i @stoplight/spectral

Weekly Downloads

29,890

Version

6.5.0

License

Apache-2.0

Unpacked Size

19.9 kB

Total Files

4

Last publish

Collaborators

  • joanna026
  • darekplawecki
  • rownskim
  • iwonadsmartbear
  • damian-polewski-sb
  • micryc
  • olgal123
  • hpetreskisb
  • kapibara_npmiara
  • kamil-sbear
  • lukaszzazulak
  • lukaszm-sb
  • sergiov85sb
  • sb-akshaythakar
  • sb-rohitdesai
  • sb-yogeshjadhav
  • sb-venkatyadavilli
  • sb-ankitapal
  • sb-harshitajadhav
  • sb-maitheelideshpande
  • sb-thakurrohit
  • mzheng_sb
  • troydm
  • naumanali__
  • mmurphy_stoplight
  • clanzo
  • kaylachun
  • brendarearden
  • danielwhite-stoplight
  • ed-stoplight
  • vazha
  • chohmann
  • wmhilton
  • mallachari
  • p0lip
  • paulatulis
  • ksoviero-stoplight
  • mmarti21
  • stoplight-devops
  • stoplight-spectral-bot