OpenAPI Specification & Swagger Tools - Zero To Master

Explore starting open API specification with a code-first approach using Swagger Hub Explorer to generate an initial OpenAPI document from existing APIs and test them.

Explore a code-first approach to generate the OpenAPI specification by testing REST APIs with Swagger Hub Explorer, using mock data from swap.dev and reqres.in.

Learn how to generate and export OpenAPI specifications from tested APIs using Swagger Hub Explorer in a code-first approach, publish to space, and review definitions with Swagger Editor and UI.

Embrace a design-first approach by turning business requirements into open API specifications, enabling faster server and client generation with the Swagger Editor and YAML or JSON formats.

Explore the history of YAML and why it is considered better than JSON and XML for open API specifications and configurations, highlighting its indentation-based syntax.

Write your YAML file using a JSON-to-YAML converter, and practice converting between YAML and JSON. Explore key-value structure, indentation, hyphen lists, and comments in YAML for open API specification workflows.

Write a minimal OpenAPI specification in YAML by defining OpenAPI version, info with title and version, and an empty paths array.

Dive into the open api info object, covering mandatory fields like title and version. Learn to define contact and license objects with optional fields, urls, emails, names, and identifiers.

Update the open api specification by adding description, terms of service, license, and a contact object (name, url, email) in the info section, using yaml pipe syntax and proper indentation.

Learn how to define and document server details in OpenAPI using the optional servers object, including URL, description, variables, and placeholder substitution for development, staging, and production environments.

Explore how to define api paths in the OpenAPI specification, including path objects, operation objects, requests, and responses, while organizing metadata like servers and contact details.

Define the first OpenAPI path for the Easy Shop categories endpoint using a relative /categories path, a get operation, and a JSON array of category objects.

Define your first API path in Swagger UI using an OpenAPI specification. Build an operation object for /categories with a 200 JSON response and a categories array (id, name).

Describe how to define query parameters in an OpenAPI spec, using category id as a query parameter to filter /categories, specify integer schema, and view examples in swagger UI.

Demonstrate how to use the try it out button in Swagger UI to test API specifications, modify query parameters, view curl and request URL, and observe minimum and maximum validation.

Learn to extend an OpenAPI specification by adding a get path with a required path parameter, describe the placeholder, and return a single category object.

Build a get api using path parameters with open api and swagger. Require category id as a path parameter, type integer 100 to 1000, returning id and name.

Extend the open API specification by adding new category and product endpoints, enabling category-based product listings and detailed product responses.

Describe and implement product related APIs using OpenAPI specification and Swagger tools, including listing products and returning product details for Easy Shop.

Extend an open api specification with a new orders post api to create orders using a request body with products and address, returning a 201 created order id.

Explore how to describe an HTTP PUT operation in an OpenAPI specification using Swagger tools, detailing an order update scenario with order ID, products, and address, and a 200 response.

Describe and implement a delete operation in Open API specification to cancel orders by a required query parameter order ID, returning 204 no content, as shown in swagger UI.

Describe the get orders api within an OpenAPI specification, detailing a required integer orderId query parameter, a 200 json response with orders, products, and address details, plus reusable schemas.

Recap the parts object in OpenAPI. Learn to define paths, path items, operations, parameters, request bodies, responses, and schemas with content types and media maps.

Explore a visual OpenAPI specification map to learn the structure, the mandatory elements, and how to define paths, requests, responses, parameters, and content in OpenAPI 3.0.

Describe api fields using common mark syntax inside the open api specification. Format with headings, bold, italic, lists, links, and code blocks for rich descriptions.

Learn to craft engaging open API documentation by applying CommonMark syntax to open API descriptions in Swagger UI, creating clear headings, emphasis, and structure.

Learn how to apply common mac syntax across an OpenAPI specification to describe fields like quantity, clarifying stock value versus order item counts, with multiline YAML descriptions.

Explore how to use the examples object in OpenAPI to provide multiple, labeled examples for request bodies, parameters, and responses, improving Swagger UI clarity and consumer understanding.

Organize and group your OpenAPI specification by introducing tags at the root and assigning them to operations, enabling Swagger to display APIs by categories like categories, products, and orders.

Explore how the components section in OpenAPI reduces duplication by centralizing schemas, parameters, and responses, so changes apply in one place via $ref across paths and operations.

Learn to define reusable parameters in OpenAPI by creating a components block and referencing via $ref to avoid duplication across get and delete operations.

Define address and product schemas as reusable components in OpenAPI and replace inline definitions with $ref references to reduce duplication across API operations.

Define a reusable category schema in OpenAPI components, reference it in both array and single object responses via $ref, and build three schemas (address, product, category) for reuse.

Learn to define reusable responses in the components object of an OpenAPI specification, including a reusable 500 internal server error, and reference it across APIs with inline or external definitions.

Explore the OpenAPI data types, including string, number, integer, boolean, object, array, date, date-time, and binary, and learn how they define schemas, requests, and responses.

Learn to represent numbers in open api specification using integer and number types, with optional format like int 32, int 64, float, and double, plus minimum and maximum values.

Explore how string data type uses formats like date, time, password, byte, and binary to model dates, times, and binary data in OpenAPI, with min length, max length, and pattern.

Learn how to define the boolean data type in OpenAPI, enforcing true or false values, and note that OpenAPI 3.x treats files under string and handles null values differently.

Explain how to use the object data type in open API, define properties and mandatory fields with required, and apply read only or write only to control data flow.

Explore the array data type in OpenAPI specifications, using items to define each element, and min items, max items, and unique items for validation, including nested arrays.

Explore how to define strict valid values with the enum keyword in OpenAPI specifications, use them for query parameters like sort order (asc, desc), and document allowed states clearly.

Learn how to implement inheritance and polymorphism in the OpenAPI specification using oneOf, anyOf, allOf, and not, and understand their purpose for modeling diverse request and response shapes.

Explore how to implement inheritance in open API specs using the allOf keyword, inheriting product properties into mobile and laptop schemas with unique fields like network type and ram.

Explore polymorphism in OpenAPI using the oneOf keyword to constrain a request body to either mobile or laptop products, with address schemas and validation.

Explore the anyOf keyword in OpenAPI, contrast it with oneOf and not, and show how responses use the order summary and order address based on the fetch type.

Explore visual examples to understand oneOf, anyOf, allOf, and not keywords in OpenAPI, applying sub schemas to determine valid outputs like red cat, white cat, red dog, and normal dog.

Review pending OpenAPI objects, compare root and path level details, and outline where security, external docs, and x-extensions fit while detailing operation ID and deprecated features.

Define unique operationId values in an OpenAPI spec to name API operations; leverage code generators for method naming and enable linking between operations across paths.

Use the deprecated field in an OpenAPI operation to mark it as deprecated, signaling consumers not to use it and indicating potential future deletion for backward compatibility.

Learn how to define links in OpenAPI 3.0 to relate API responses to other operations. Map response data to request parameters using dollar response body and operation IDs.

Define custom fields in OpenAPI using the x-hyphen extension pattern to extend root and object level information while Swagger UI may not render these extensions.

Explore how to use externalDocs in OpenAPI to link to external resources, with a mandatory url and optional description, at root, in parts, and in path operations.

Describe security in the OpenAPI specification by defining security schemas under components and using the security keyword to enforce authentication such as basic, bearer, api keys, and OpenID Connect.

Define and describe basic and bearer authentication in OpenAPI specifications, detailing security schemas in components, authorization headers, base64-encoded username:password, and JWT bearer tokens.

Define security schemes under components for HTTP basic and bearer authentication using JWT, reference them in root security, and demonstrate via Swagger UI authorize.

Explain how to define API key security in an OpenAPI specification, including where to send the key (header, query, or cookie), naming the key, and referencing the security scheme.

Learn to describe OAuth2 and OpenID Connect security inside OpenAPI specifications, covering flows, scopes, tokens, and how to integrate authorization code, implicit, and client credentials schemes.

Define OAuth2 security schemes in an OpenAPI specification, configure the authorization code flow with authorization URL and token URL, and specify scopes such as read, write, and admin.

Define security at the operation level in the OpenAPI specification to override root-level settings, enabling per-endpoint authentication like basic only or no security.