Topolearn

Learn OpenAPI

Machine-readable descriptions of HTTP APIs for docs, codegen and testing

13 lessons · 3 hours · 4 levels · covers OpenAPI 3.1 (with 3.2 additions)

The OpenAPI Specification is a standard, language-agnostic format (YAML or JSON) for describing HTTP APIs: their paths, parameters, request and response bodies, and security. From one OpenAPI document teams generate interactive documentation, client SDKs and server stubs, mock servers, and contract tests, making it the backbone of API-first development.

Sign in free to track progressOfficial docs ↗

Before you start

OpenAPI builds on these; the tree links to the exact lessons you need.

HTTP & the webEssentials levelcurlEssentials levelYAMLEssentials level

How deep do you want to go?

1. EssentialsRead and write simple code, do the everyday basics4 lessons · 42 min in total
2. PracticalUse it productively at work, with the usual idioms7 lessons · 1 hour in total
3. AdvancedThe less common features, performance and trade-offs10 lessons · 2 hours in total
4. ExpertInternals and the edge cases experts know13 lessons · 3 hours in total

The OpenAPI tree

OpenAPIWhat OpenAPI is forWhat OpenAPI is forDocument structureDocument structurePaths, operations and parametersPaths, operations andparametersRequest bodies and responsesRequest bodies andresponsesSchemas with JSON SchemaSchemas with JSONSchemaComponents and $refComponents and $refSecurity schemesSecurity schemesSeeing headers: -i, -I, -v and -HSeeing headers: -i, -I,-v and -HJSON APIs and authenticationJSON APIs andauthentication
Essentials and Practical shown (7 of 13 lessons); the full list is below. Click a lesson to read it.

All 13 lessons, in order

Describing an API

  1. What OpenAPI is for · Essentials · 8 min

    An OpenAPI document is a machine-readable contract for an HTTP API that drives docs, client generation, mocks and tests.

  2. Document structure · Essentials · 10 min

    Know the top-level fields of an OpenAPI document: openapi, info, servers, paths, components, security and tags.

  3. Paths, operations and parameters · Essentials · 12 min

    Describe endpoints with path templates, operations with operationIds and tags, and path, query, header and cookie parameters.

  4. Request bodies and responses · Essentials · 12 min

    Describe request and response payloads by media type, list responses by status code, and document headers and examples.

  5. Security schemes · Practical · 12 min

    Declare API keys, HTTP bearer and basic auth, OAuth 2.0 flows and OpenID Connect, and apply them globally or per operation.

Schemas and reuse

  1. Schemas with JSON Schema · Practical · 15 min

    Model data with OpenAPI 3.1 schemas: types, required, formats, enums, nullability via type arrays, and constraints.

  2. Components and $ref · Practical · 12 min

    Define schemas, parameters, responses and examples once under components and reference them with $ref, across files too.

  3. Polymorphism: oneOf, anyOf, allOf, discriminator · Advanced · 15 min

    Compose schemas with allOf, describe alternatives with oneOf and anyOf, and help tools pick the right type with a discriminator.

Tooling and workflows

  1. Generating clients, servers and types · Advanced · 12 min

    Generate typed SDKs, server stubs or TypeScript types from an OpenAPI document, and decide between design-first and code-first.

  2. Linting, docs and mock servers · Advanced · 12 min

    Validate and lint documents with Redocly or Spectral, publish reference docs, and serve mocks with Prism.

  3. Versioning and breaking-change detection · Expert · 12 min

    Classify API changes as compatible or breaking, diff OpenAPI documents in CI, and plan versioning and deprecation.

  4. Contract testing against the document · Expert · 15 min

    Prove the implementation matches the document with property-based API testing, runtime validation and consumer checks.

Advanced descriptions

  1. Webhooks, callbacks, links and 3.2 additions · Expert · 15 min

    Describe outgoing requests with webhooks and callbacks, connect operations with links, and know what OpenAPI 3.2 adds.