v311

OpenAPI Fundamentals

This course is designed to provide an overview of OpenAPI v3.1, from the bare essentials to extending OpenAPI, Special Interest Groups, and other specifications that are part of the OpenAPI Initiative.

Course Materials

• Chapter 1 - Course Overview
• Chapter 2 - Introducing OpenAPI
• Chapter 3 - OpenAPI Basics
• Chapter 4 - Creating an OpenAPI Description
• Chapter 5 - Using an OpenAPI Description
• Chapter 6 - Extending OpenAPI

Outline

The following sections provide an outline of the course modules.

Chapter 1: Course Overview

Placeholder for a courser overview section, with the expectation any reusing these course materials will provide their own.

Chapter 2: Introducing OpenAPI

Understand the history of OpenAPI, its raison d'etre, and its place in the API economy.

Topics

• Introduction
  • Chapter Overview
  • Learning Objectives
• Introducing the API Economy
  • The Role of APIs
  • APIs-as-Products
• Describing APIs
  • Describing Software Interfaces
  • What are API description languages?
  • What does an API description language solve for?
  • What API description languages exist?
• An Overview of OpenAPI
  • What is OpenAPI?
  • Other OpenAPI Initiative Specifications
• Knowledge Check

Chapter 3: OpenAPI Basics

Understand the basic structure of an OpenAPI Description and how it reflects APIs published in the marketplace.

Topics

• Introduction
  • Chapter Overview
  • Learning Objectives
• HTTP, APIs, and OpenAPI
  • The Role of HTTP
  • Mapping OpenAPI to HTTP
  • Versions of OpenAPI
• High-Level Structure
  • Structure Overview
  • Providing Information through the Info Object
  • Examples of the Info Object
• Describing API Shape
  • URLs, Paths, and Methods
  • Relationship Between Paths, Path Items and Operations
• Describing Parameters, Requests, and Responses
  • Providing Parameters
  • Using OpenAPI to Describe API Requests and Responses
  • Representing Data Using a Schema Object
  • Creating a Response Object
• Defining Reusable Objects
  • Objects That Can Be Reused
  • Example of Object Reuse
• Other Features
  • Grouping Operations using Tags
  • Describing Security Requirements
  • Supported Security Requirements
  • Security Requirement Example
  • Using Specification Extensions
• Course Scope
  • Features Not Covered Here
• Knowledge Check

Chapter 4: Creating an OpenAPI Description

Create an OpenAPI Description using both code-first and design-first methodologies.

Topics

• Introduction
  • Chapter Overview
  • Learning Objectives
• Using Design-first
  • Why Design-first Works
  • Creating an OpenAPI Description in Swagger Editor
  • Adding an Info Object
  • Adding a Response Payload
  • Making a Response Reusable
  • Returning Consistent Error Payloads
  • Adding Tags to Operations
  • Adding Security Requirements
  • Other Information
  • Complete Example
• Using Code-first
  • Why Code-first Works
  • Code-first Using Java and springdoc-openapi
  • Comparing Design-first
  • Code-first using Python and APIFlask
  • Code-first Tasks
• Deciding on Design-first versus Code-first
  • Which Approach Fits Your Needs?
  • Taking a Lifecycle View
• Knowledge Check

Chapter 5: Using an OpenAPI Description

Use an OpenAPI Description with a range of tools that help you throughout the API lifecycle.

Topics

• Introduction
  • Chapter Overview
  • Learning Objectives
• Using an OpenAPI Description and the API Lifecycle
  • The API Lifecycle
• Generating API Documentation
  • Use Case for Generating API Documentation
  • Example of Generating API Documentation
  • Task: Generate API Documentation Using Redoc
• Generating an API Client
  • Use Case for Generating an API Client
  • Example of Generating an API Client
  • Task: Generating an API Client using Kiota
• Applying Governance
  • Use Case for Applying Governance
  • Example of Applying Governance
  • Task: Add Governance Rules to a Spectral Ruleset
• Knowledge Check

Chapter 6: Extending OpenAPI

Understand how OpenAPI is extended in the ecosystem through Specification Extensions and Special Interest Groups.

Topics

• Introduction
  • Chapter Overview
  • Learning Objectives
• Using Specification Extensions
  • What are Specification Extensions?
  • Example: UK Open Banking
  • Example: Redoc
  • Example: Azure API Management
  • Specification Extension Scope
• Overlay Specification
  • Updating OpenAPI Descriptions
  • Using the Overlay Specification
  • How Overlay Helps in Updating OpenAPI Descriptions
• Arazzo Specification (Workflows SIG)
  • Describing Sequences of API Calls
  • Describing a Workflow
  • Describing Steps
  • How Arazzo Helps in Making Multiple API Calls
• Knowledge Check