Learn OpenAPI

Last updated: September 2026

OpenAPI is the open standard for describing HTTP APIs in a machine-readable document, and this hub collects Scalar's guides to writing, documenting, checking, and using those documents. The articles are written for developers and technical writers who work with an API description every day, whether they write it by hand or generate it from code.

Read them in this order if you are new to OpenAPI. Each article stands on its own, so skip ahead to whatever you are working on.

Start here

1. What is OpenAPI?: what the specification is, how a document is structured, and what you can build from one.
2. OpenAPI 3.1 vs 3.0: what changed, what OpenAPI 3.2 adds, and a migration checklist.
3. OpenAPI vs Swagger: why there are two names, and how the specification differs from the Swagger tools.
4. JSON Schema vs OpenAPI: how the Schema Object relates to plain JSON Schema.
5. OpenAPI security schemes: describing API keys, HTTP auth, OAuth 2.0, OpenID Connect, and mutual TLS.

Documentation

6. What is an API reference?: the part of your docs that describes every endpoint, and what makes a good one.
7. OpenAPI documentation: how to write descriptions, examples, tags, and Markdown so your OpenAPI document produces useful docs.
8. API documentation best practices: twelve habits that make an API easy to adopt, with a quick audit checklist.
9. llms.txt for API docs: making API documentation readable by AI tools and agents.

Quality and governance

10. OpenAPI linting: catching errors and style problems in API descriptions before they reach users.
11. Spectral rules: how Spectral rulesets work, which built-in rules matter, and how to write your own.
12. API catalog: keeping track of every API in an organization with a catalog or registry.

Using the document

13. What is an API client?: tools for sending and testing requests, and how they import OpenAPI documents.
14. API mocking: running a mock server from an OpenAPI document so frontend and backend work can happen in parallel.

Why this order

Most people meet OpenAPI the same way. Someone hands them a file called openapi.yaml (or swagger.json), and the first questions are what it is, which version it uses, and why the names differ. The first section answers those, and adds the two topics that trip people up most once they start editing: schemas and authentication.

The second section is about the most common reason an OpenAPI document exists at all, which is documentation. A renderer can turn any valid document into a reference, but only the descriptions, examples, and tags you write make it a good one. These articles show how, field by field.

Once several people edit a document, or several teams publish APIs, quality stops being a matter of care and becomes a matter of automation. The third section covers linting, rulesets, and catalogs. The last section covers the tools that consume the document day to day.

Every article uses the terminology of the OpenAPI Specification itself and cites the relevant version of it: 3.2.1, 3.1.2, or 3.0.4. The examples are meant to be copied: paste them into a validator or a renderer and see the result for yourself.

We build OpenAPI tooling, so we have an interest here. Where Scalar is a good fit, the articles say so and link to it. They also link to the specification, to open-source alternatives, and to other vendors' documentation where those are the better fit.

When you are ready to go further, the SDK guides cover generating client libraries from the same document, and the MCP guides cover exposing it to AI agents. The Learn home page lists every topic.

Related

• Learn: What is OpenAPI? · OpenAPI documentation · Learn SDKs
• Docs: Scalar and the OpenAPI Specification
• Product: Scalar API reference — open-source, interactive documentation from any OpenAPI document.