Agenda

Terms of Service

Schema Object

Post Operation

Versioning the API

Implementing the GET Method

Swagger Validation

Conclusion

Designing an API

Business Taxonomy

OpenAPI 2.0 Design

Keeps Internal Stakeholders Aligned

OpenAPI Example

Intro

REST API example

What is OpenAPI?

Benefits of OpenAPI

Guidance

OpenAPI tooling

API validator

OpenAPI Example

Describe the REST API Request

Conclusion

Introduction

Short Version

What's an API?

What's an Open API?

How to use Open APIs

What is OpenAPI?

OpenAPI Example

How to use OpenAPI for Open APIs

Summary and Wrap-up

Start

Introductions

Arnaud's background in API design

What is OpenAPI and how is it used in API design?

In Case You Missed It

Building an API from an empty page, and thinking about the business needs so we only design what we need

Getting started with OpenAPI version and "info" block

Defining the "servers" section and best practices around versioning your API using the URI path of a URL

Defining our OpenAPI "paths" and putting a placeholder for "components" that we'll fill in later

Adding an API path to search for books, API design discussion and HTTP verbs

Adding a "summary" to our GET operation, and status codes

discussion about response data types, and how to structure that data to allow future-proofing our API

Which attributes should we return for a list of books? Discussion of RESTful design over-fetching and under-fetching

Discussion about what an "ID" field should contain: what does our tech stack define, versus user expectation

Finishing our schema and converting it to an OpenAPI "component" for re-use

Discussion about reusing schemas in an embedded way to extend schemas

Adding an example definition in OpenAPI

Community Shoutouts

Automated Documentation

Swagger Ui Is Not Documentation

Json Schema

Inheritance

Security Schemes

Issues with the Open Api Format

Tools

To Edit an Open Api File Manually Use Visual Studio Code

Bundling

Openapi Test

Intro

What is OpenAPI?

OpenAPI Initiative

External Docs

Benefits of an OpenAPI Specification

Automated Tests & Monitors

API management tools

How to get involved in OpenAPI

Conclusion

Intro

Generators

Configuration Options

Generated Folder Structure

Implementing the API Controller

Implementing an Endpoint

Returning a Status Code

Maven Plugin

Troubleshooting generated code

Conclusion

Welcome and Housekeeping

OpenAPI 3.1 Community Poll Results

Does OpenAPI 2.0 still work?

Summary and Description Override

Swagger vs OpenAPI

Can we consider all new APIs with 3.1 backward compatible?

Errors and Warnings

JSON Schema Tooling

JSON Schema Dialects

Conclusion

Intro

Why Describe APIs?

Benefits of using OpenAPI Specification

Anatomy of an OpenAPI Specification

Components

OpenAPI Example

Responses

OpenAPI Tools

Conclusion

Resources

What Is Open Api

How Do I Create an Open Api Definition

Step 2 Clone the Repository

Step 3 Familiarize with the Repository

Path to the Root File

Introduction to Swagger

What is OpenAPI

Generate Code

Swagger UI

Swagger Live Demo

Generate Client SDK

Swagger SDK

What is Swagger?

Swagger Tools

Conclusion

What is an OpenAPI Specification?

Swagger editor

Simple Key-Value Pair

Fixing warnings

Collections in YAML

Variables

Defining Resources

Indentation in YAML

Summary

Conclusion

Intro

Version of the API

Define the operations

Responses in Swagger