Swagger / OpenAPI Specification

Module 1: API-First Design & OpenAPI

• API-first methodology: design before code
• OpenAPI 3.0 vs Swagger 2.0: key differences
• Specification anatomy: info, paths, components
• YAML vs JSON: choosing your format
• Tools: Swagger Editor, VS Code extension, Stoplight
• OpenAPI vs RAML vs API Blueprint: comparison

Module 2: Defining Paths & Operations

• Path items: parameterised URL patterns
• HTTP methods: get, post, put, patch, delete
• Operation object: summary, description, operationId
• Tags: grouping operations by resource
• Parameters: path, query, header, cookie
• Request body: content and schema

Module 3: Data Schemas

• JSON Schema in OpenAPI: type, format, enum
• Object schemas: properties and required fields
• Array schemas: items and uniqueItems
• Schema composition: allOf, oneOf, anyOf
• Nullable and optional properties
• Reusable schemas in components/schemas

Module 4: Responses & Error Handling

• Response status codes: 2xx, 4xx, 5xx
• Response body schema definition
• Headers in responses
• Error object design: RFC 7807 problem details
• Multiple response schemas per status
• Default response for unexpected errors

Module 5: Authentication & Security

• securitySchemes: apiKey, http, oauth2, openIdConnect
• OAuth 2.0 flows in OpenAPI: authCode, clientCreds
• Applying security globally and per-operation
• Scopes for fine-grained authorisation
• JWT Bearer token documentation
• Basic authentication definition

Module 6: Code Generation & Tooling

• OpenAPI Generator: client SDK generation
• Server stub generation: Node.js, Spring, FastAPI
• Swagger Codegen vs OpenAPI Generator
• Customising generated code templates
• Swagger UI: interactive documentation
• Redoc: alternative documentation renderer

Module 7: Contract Testing with OpenAPI

• Dredd: automated API specification testing
• Schemathesis: property-based API testing
• Spectral: OpenAPI linting rules
• Postman contract testing with OpenAPI import
• Schema drift detection in CI/CD
• Version management and breaking change detection

Module 8: API Governance & Lifecycle

• API style guides: naming and design standards
• Spectral rulesets for style enforcement
• OpenAPI in CI/CD: lint, validate, publish
• API versioning: URI vs header approach
• Stoplight: collaborative API design platform
• AsyncAPI for event-driven API documentation

Our API design and automation instructors are API architects and developer experience specialists who have designed OpenAPI specifications for public and internal APIs at software companies, helped teams adopt Swagger tooling, and built advanced Postman automation frameworks for CI/CD pipelines. They teach API-first design as a discipline, not just a documentation practice.