Skip to content
Tutorials Center
My learning

Topics

OpenAPI and Swagger Tutorial

Learn OpenAPI and Swagger step by step: 37 lessons in 9 chapters with examples, quizzes, diagrams and projects.

Start learning →

of lessons completed

Getting Started

  1. 1 What Is OpenAPI? Describing HTTP APIs for Humans and Machines Learn what OpenAPI is, why a machine-readable API description matters, what you can build from one document, and how it fits next to REST and JSON.
  2. 2 OpenAPI vs Swagger: History, Versions and Which to Use Understand the difference between OpenAPI and Swagger, how the specification evolved from 2.0 to 3.1 and 3.2, and which version you should pick for new work.
  3. 3 Your First OpenAPI Document: Build a Pet Store API Step by Step Write a complete OpenAPI 3.1 document from scratch: info, servers, one path, parameters, a response schema and an error. Includes a live checker stand-in.
  4. 4 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.

Specification Basics

  1. 5 OpenAPI Document Structure: The Root Fields Explained A map of an OpenAPI 3.1 document: openapi, info, servers, paths, webhooks, components, security, tags and externalDocs, with a live structure explorer.
  2. 6 OpenAPI Info, Servers, Server Variables and Tags Fill in the descriptive part of an OpenAPI document: the info object, contact and license, servers with variables, tags and external docs, plus a URL resolver.
  3. 7 YAML and JSON Syntax for OpenAPI Documents Learn the YAML and JSON syntax you need to write OpenAPI by hand: maps, lists, quoting, multiline text, anchors and the pitfalls that break documents.
  4. 8 OpenAPI Data Types and Formats: string, integer, number, boolean Master OpenAPI data types and formats: string, number, integer, boolean, array, object, null, plus date-time, uuid, email, int64, binary and 3.1 type arrays.

Paths, Schemas and Components

  1. 9 OpenAPI Paths and Operations: Describing Endpoints Learn how the OpenAPI paths object works: path items, HTTP methods, path templates, operationId, summary, tags, deprecation and how to design clean endpoints.
  2. 10 OpenAPI Parameters: Path, Query, Header and Cookie Describe API inputs with OpenAPI parameters: the four locations, required, schema, style and explode for arrays, content-based parameters and a request builder demo.
  3. 11 OpenAPI Request Bodies and Media Types (JSON, Forms, Files) Describe request bodies in OpenAPI: requestBody, content and media types, JSON payloads, form-urlencoded, multipart file uploads, examples and body validation.
  4. 12 OpenAPI Responses: Status Codes, Headers and Error Shapes Describe every outcome of an API call in OpenAPI: response objects, status codes, ranges, default, headers, empty bodies, error schemas and links.
  5. 13 OpenAPI Schema Objects and JSON Schema: Describing Your Data Model your API data with OpenAPI schemas: objects, properties, required, additionalProperties, arrays, enums, defaults, examples, discriminators and JSON Schema in 3.1.
  6. 14 OpenAPI Components and $ref: Reuse Schemas, Parameters and Responses Keep OpenAPI documents DRY with components and $ref: schemas, parameters, responses, headers, examples, request bodies, local and external references, and resolving them.
  7. 15 OpenAPI allOf, oneOf, anyOf, not and Discriminator Explained Combine schemas in OpenAPI: allOf for inheritance, oneOf and anyOf for alternatives, not, discriminator for polymorphism, with a live evaluator and design pitfalls.

Security Schemes

  1. 16 OpenAPI Security Schemes: Defining and Applying Authentication Describe API authentication in OpenAPI: securitySchemes in components, the security requirement object, global versus per-operation security, AND/OR logic and public endpoints.
  2. 17 OpenAPI API Key, Basic and Bearer (JWT) Authentication Describe API key, HTTP Basic and Bearer token (JWT) authentication in OpenAPI: apiKey in header, query or cookie, http schemes, bearerFormat, and what each looks like on the wire.
  3. 18 OpenAPI OAuth 2.0 and OpenID Connect: Flows, Scopes and PKCE Describe OAuth 2.0 and OpenID Connect in OpenAPI: authorizationCode, clientCredentials and other flows, scopes per operation, openIdConnectUrl, mutualTLS and a PKCE demo.

Code Generation

  1. 19 How Code Generation from OpenAPI Works See how tools turn an OpenAPI document into client SDKs, server stubs and models, what they can and cannot generate, and build a tiny generator yourself.
  2. 20 OpenAPI Generator on the Command Line Learn the openapi-generator-cli commands, config files, additional properties, custom templates and the ignore file, with runnable stand-ins for the file logic.
  3. 21 Generating Server Stubs from an OpenAPI Spec Learn how server generators turn an OpenAPI document into routes, interfaces and controller stubs, how to keep your own logic separate, and try a stand-in router.
  4. 22 Generating and Publishing Client SDKs Generate and ship client SDKs from OpenAPI: choose libraries, handle authentication and errors, add retries in a wrapper, version the package and publish from CI.

Documentation Tools

  1. 23 Swagger UI โ€“ Interactive API Documentation Learn how Swagger UI turns an OpenAPI document into interactive docs: embedding, Docker, Try it out, authorization, CORS and configuration, with a runnable stand-in.
  2. 24 Redoc and Static API Documentation Build static OpenAPI documentation with Redoc and Redocly CLI, group tags, add code samples, compare Swagger UI, Redoc and Scalar, and see a Markdown generator stand-in.
  3. 25 Writing Great API Descriptions and Examples Learn how to write summaries, Markdown descriptions, tags, examples and deprecation notes in OpenAPI so generated docs are clear, plus a runnable documentation coverage checker.

Validation and Contract Testing

  1. 26 Linting OpenAPI with Spectral Lint OpenAPI documents with Spectral: built-in rulesets, severities, custom rules with given and then, overrides and CI. Includes a runnable mini rule engine stand-in.
  2. 27 Validating Requests and Responses Against OpenAPI Use an OpenAPI document to validate incoming requests and outgoing responses at runtime, learn what to check, where to place validators, and run a stand-in validator.
  3. 28 Mock Servers from OpenAPI with Prism Run a mock API straight from an OpenAPI document with Prism: static and dynamic responses, the Prefer header, validation proxy mode, and a runnable mock server stand-in.
  4. 29 Contract Testing with Schemathesis, Dredd and Pact Learn contract testing for OpenAPI: property-based testing with Schemathesis, example-based tests with Dredd, consumer-driven contracts with Pact, plus a runnable fuzz tester.

Design-first Workflows

  1. 30 Design-First vs Code-First API Development Compare design-first and code-first OpenAPI workflows, learn the steps of each, when to choose which, and try a runnable mini code-first spec generator and a decision scorecard.
  2. 31 API Style Guides and Governance with OpenAPI Write an API style guide that your OpenAPI lint rules can enforce: naming, plural nouns, pagination, problem details errors, review process, with a runnable style checker.
  3. 32 API Versioning and Detecting Breaking Changes Learn which API changes break clients, how to version OpenAPI documents and APIs, deprecate safely, and run a stand-in diff tool that classifies breaking and compatible changes.
  4. 33 Splitting and Bundling Large OpenAPI Specs Organize a large OpenAPI description into many files with external $ref, then bundle it for tools; includes folder layouts, circular references, and a runnable bundler stand-in.

Projects and Practice

  1. 34 Project: Design a Bookstore API Contract Build a complete design-first OpenAPI contract for a bookstore: requirements, paths, schemas, errors and examples, then check it with a runnable structural validator.
  2. 35 Project: A Spec Quality Gate for CI Build a continuous-integration quality gate for an OpenAPI repository that lints, detects breaking changes, builds docs and generates an SDK, with a runnable gate-logic stand-in.
  3. 36 Project: Build a Contract Test Suite Build a contract test suite from an OpenAPI document: example-based tests, generated boundary cases and response checks against a stand-in API, then learn how to run it for real.
  4. 37 Practice: Review a Flawed OpenAPI Document Practice reviewing an OpenAPI document: find ten planted mistakes, check your list against a runnable reviewer, use a tooling cheat sheet and test yourself with a mixed quiz.