Skip to content
Tutorials Center
My learning

Topics

Lesson 4 of 37 ยท Getting Started

OpenAPI Tooling: Editors, Linters, Validators and Viewers

Tour the OpenAPI toolbox: Swagger Editor, Swagger UI, Redocly CLI, Spectral, VS Code extensions and more, with exact commands and a custom lint-rule stand-in.

An OpenAPI document is only useful if you can write it comfortably, check it automatically and show it to others. A healthy ecosystem of tools covers each of those jobs. This lesson maps the toolbox, gives you the exact commands for the most common tools, and builds a stand-in linter so you understand what a rule actually is.

The tools below run on your own computer or in your CI system. They cannot run on this website, so the commands are shown as read-only snippets. Check each tool's own documentation for the latest flags, because command-line options change between releases.

The four jobs

Four jobs for tools

Edit Write with autocomplete
Lint Enforce your style rules
Validate Check the document is legal
View Render docs for readers
1 / 2

Editing

  • Visual Studio Code with an OpenAPI extension (for example "OpenAPI (Swagger) Editor") gives you outline navigation, autocomplete and a live preview pane. Generic YAML extensions add schema-based completion if you point them at the OpenAPI JSON Schema.
  • Swagger Editor is a web app with the YAML on the left and rendered documentation on the right. You can run it locally with Docker:
Terminal
docker run -p 8081:8080 swaggerapi/swagger-editor
# then open http://localhost:8081
  • Stoplight Studio, Postman, Insomnia and IntelliJ-based IDEs offer visual or form-based editing as well.

Validating

Validation answers "is this a legal OpenAPI document?". Most CLI tools include it. Two popular choices:

Terminal
# Redocly CLI: lint also validates structure
npx @redocly/cli lint openapi.yaml

# Spectral: ruleset based; "spectral:oas" is the built-in OpenAPI ruleset
npx @stoplight/spectral-cli lint openapi.yaml

A validation error tells you the exact path inside the document (for example paths./pets.get.responses) and what is wrong.

Linting with your own rules

Linting goes beyond legality: it enforces your team's conventions (every operation has a summary, paths use kebab-case, errors use a shared schema). Spectral reads a ruleset file named .spectral.yaml:

YAML
extends: ["spectral:oas"]
rules:
  operation-must-have-tag:
    description: Every operation needs at least one tag.
    severity: error
    given: "$.paths[*][get,post,put,patch,delete]"
    then:
      field: tags
      function: truthy

given selects parts of the document with a JSONPath expression, and then applies a function to each match. Redocly has a similar redocly.yaml configuration with built-in rules you switch on or off.

Viewing

  • Swagger UI renders interactive documentation with a Try it out button for each operation. Docker one-liner (mount the folder that contains your file):
Terminal
docker run -p 8082:8080 -e SWAGGER_JSON=/spec/openapi.yaml -v "$PWD":/spec swaggerapi/swagger-ui
  • Redoc produces a clean three-column reference page; npx @redocly/cli preview-docs openapi.yaml serves it locally and npx @redocly/cli build-docs openapi.yaml writes one static HTML file.
  • Scalar, RapiDoc and Stoplight Elements are other viewers with similar goals.

The documentation tools chapter goes deeper into choosing and theming a viewer.

A lint rule is just a function over the document

To see what Spectral does under the hood, this stand-in implements the same idea in Python: each rule picks nodes (the "given") and checks a condition (the "then").

Python Stand-in: a mini rule-based linter

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Put it in your workflow

flowchart LR
  E["Edit in IDE"] --> L["Lint locally"]
  L --> C["Commit + pull request"]
  C --> CI["CI runs lint + validate"]
  CI --> D["Publish docs"]

The same lint command runs on your laptop and in CI, so a pull request that breaks the rules fails automatically.

A typical CI step is one line: npx @redocly/cli lint openapi.yaml or the Spectral equivalent. A non-zero exit code fails the build.

Start with the default ruleset, then add your own rules one at a time as the team agrees on conventions. A hundred noisy rules on day one gets the linter ignored.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the main difference between validation and linting?

    Validation is about the specification's rules; linting adds your own conventions on top.
  2. 2. Which tool is best known for interactive documentation with a Try it out button?

    Swagger UI renders operations and lets readers send requests from the page.
  3. 3. In a Spectral rule, what does the given field do?

    given selects nodes; then applies a function such as truthy to them.
  4. 4. Where should the lint command run besides your laptop?

    Running the same command in CI makes the rules enforceable.

Summary

  • Tools cover four jobs: edit, validate, lint and view.
  • IDE extensions and Swagger Editor help you write; Redocly CLI and Spectral validate and lint.
  • Swagger UI, Redoc and similar viewers turn the document into documentation.
  • A lint rule selects nodes of the document and checks a condition.
  • Run the same checks locally and in CI.

Next: Document structure and the root fields