OpenAPI / Swagger

What you'll learn

• Explain the OpenAPI Specification, its relationship to Swagger and the structure of a 3.1 document.
• Describe paths, operations, parameters, request bodies, responses and examples precisely.
• Model data with JSON Schema types, constraints, composition, discriminators and 3.1 nullability.
• Document security schemes, OAuth scopes and consistent Problem Details error responses.
• Apply design conventions, evolve APIs without breaking clients and describe webhooks and uploads.
• Use documentation, linting, mocking, contract testing and code generation tools in an API-first workflow.

Syllabus

OpenAPI Foundations

1. What OpenAPI and Swagger Are
2. Structure of an OpenAPI Document
3. Design-First Versus Code-First

Paths, Parameters and Bodies

1. Paths and Operations
2. Parameters: Path, Query, Header and Cookie
3. Request Bodies, Responses and Status Codes

Schemas and Data Modelling

1. Schema Basics: Types, Formats and Constraints
2. Reuse and Composition: $ref, allOf, oneOf, anyOf and Discriminators
3. OpenAPI 3.0 Versus 3.1

Security and Errors

1. Security Schemes and Requirements
2. OAuth 2.0 and OpenID Connect in OpenAPI
3. Describing Errors Consistently

API Design Patterns in OpenAPI

1. Pagination, Filtering and Naming Conventions
2. Versioning, Evolution and Breaking Changes
3. Webhooks, Callbacks, Links and File Uploads

Documentation, Linting and Mocking

1. Interactive Documentation: Swagger UI, Redoc and Scalar
2. Validating and Linting OpenAPI Documents
3. Mock Servers and Contract Testing

Code Generation and Frameworks

1. Generating Clients and Server Stubs
2. Code-First with springdoc-openapi in Spring Boot
3. OpenAPI in Other Frameworks

API Workflow, Governance and Revision

1. An API-First Workflow in CI/CD
2. API Governance, Catalogues and AsyncAPI
3. Case Study: Designing an Orders API Contract
4. Revision and Interview Questions