Designing APIs with Swagger and OpenAPI
Joshua S. Ponelat and Lukas L. Rosenstock
  • MEAP began August 2019
  • Publication in Early 2021 (estimated)
  • ISBN 9781617296284
  • 400 pages (estimated)
  • printed in black & white

A great introduction to the design process of APIs by helping you to understand OpenAPI and Swagger.

Ben McNamara
Customer-facing and internal APIs have become the most common way to integrate the components of web-based software. Using standards like OpenAPI, you can provide reliable, easy-to-use interfaces that allow other developers safe, controlled access to your software. Designing APIs with Swagger and OpenAPI is a hands-on primer to properly designing and describing your APIs using the most widely-adopted standard.

About the Technology

Modern web applications are made of multiple components, services, and servers connected through APIs, often using HTTP and REST as their primary interfaces. These architectures rely on APIs that allow access to the functionality of a component without requiring developers to understand the details of how it was implemented. The OpenAPI specification standardizes how you describe RESTful APIs. OpenAPI is vendor-neutral and has been adopted by big tech companies such as Google, Microsoft, and Amazon.

About the book

Designing APIs with Swagger and OpenAPI is a hands-on primer for describing, planning and designing web APIs. Core Swagger contributor Josh Ponelat introduces you to a design-first paradigm that will teach you the best practices for describing and designing RESTful APIs using OpenAPI and Swagger. You’ll build upon progressively-enhanced examples as you learn to describe an API and then extend it in the kind of scenarios you’d encounter in the real world. You’ll practice skills for assessing business needs, gathering requirements, and working with a cross-functional team. And as you go, you’ll use the popular Open Source tools to define APIs, generate documentation, and build other developer-friendly components like mocks, server stubs, and client SDKs.
Table of Contents detailed table of contents

Part 1

1 Introducing APIs and OpenAPI

1.1 What is an API Ecosystem?

1.2 Describing things

1.2.1 Bridget’s Task

1.2.2 The potential of Bridget’s solution

1.3 What is OpenAPI?

1.4 Where do OpenAPI definitions fit in ?

1.5 And what is Swagger?

1.6 What about REST?

1.7 Where to use OpenAPI

1.7.1 When speed matters

1.7.2 Internal networks

1.8 Good APIs

1.9 This book

1.10 Summary

2 Getting set up to make API Requests

2.1 The problem

2.2 Getting set up with Postman

2.2.1 Installing Postman

2.3 FarmStall API

2.4 Our first request!

2.4.1 Forming the Request in Postman

2.4.2 Verification

2.5 Adding a Review to the FarmStall API

2.5.1 Verification

2.6 Practice

2.6.1 Fun API requests to make

2.7 Summary

3 Our first taste of OpenAPI definitions

3.1 The problem

3.2 Introducing the OpenAPI specification

3.3 A quick refresher on YAML

3.4 Describing our first Operation

3.5 Extending our first Operation

3.6 Summary

4 Using SwaggerEditor to write OpenAPI definitions

4.1 Introducing SwaggerEditor

4.2 Writing the smallest OpenAPI definition in SwaggerEditor

4.2.1 The smallest yet valid OpenAPI definition

4.2.2 Writing in SwaggerEditor

4.2.3 A word on validation

4.3 Adding GET /reviews into our definition

4.4 Interacting with our API

4.4.1 Executing GET /reviews

4.4.2 Adding servers to our definition

4.4.3 Executing GET /reviews (again)

4.5 Summary

5 Describing API responses

5.1 The problem

5.2 JSON Schema and the mind-blowing world of data schemas

5.2.1 JSON Schema

5.2.2 Type

5.2.3 Minimum and Maximum

5.2.4 Number vs Integer

5.3 Status Codes

5.4 Media Types (aka MIME)

5.5 Describing GET /reviews response

5.5.1 Smallest response in OpenAPI

5.5.2 GET /reviews 200 response body

5.5.3 Adding rating into our response body

5.5.4 Describing message, uuid and userId

5.5.5 Schemas

5.6 Summary

6 Creating resources

6.1 The problem

6.2 Describing POST /reviews with a request body

6.2.1 Where to find request bodies

6.3 Executing operations with request bodies

6.3.1 Adding examples to make try-it-out look pretty

6.4 Describing GET /reviews/{reviewId} with a path parameter

6.4.1 Path parameters

6.4.2 Describing the path parameter

6.5 Verifying our reviews are getting created

6.6 Summary

7 Adding Authentication and Authorization

7.1 The problem

7.1.1 The flow of POST /reviews

7.2 Getting set up for authentication

7.2.1 Challenge — Describe POST /users and POST /tokens

7.2.2 Solution — Definition changes

7.2.3 Verifying we can create users and get a token

7.3 Adding the Authorization header

7.3.1 How does OpenAPI handle authorization

7.3.2 Types of authorization (securities) supported in OpenAPI 3.0.x

7.3.3 Adding the Authorization header security scheme

7.3.4 Adding the security requirements to POST /reviews

7.3.5 Using the security feature of try-it-out

7.4 How to add security schemes in general

7.5 Summary

8 Preparing and hosting API documentation

8.1 The problem

8.2 Adding metadata information to the definition

8.3 Writing the description in Markdown

8.3.1 Markdown basics

8.3.2 Adding a rich text description to FarmStall API definition

8.3.3 Reviews Section

8.3.4 Example Reviews Section

8.4 Organizing operations with tags

8.4.1 Adding the Reviews tag to GET /reviews

8.4.2 Adding descriptions to tags

8.4.3 Adding the rest of the tags

8.5 Hosting our API documentation using and SwaggerUI

8.5.1 Preparing SwaggerUI with our definition

8.5.2 Hosting on

8.6 Notes on Part One

8.6.1 How can you apply this?

8.6.2 Next part

8.7 Summary

9 Designing a web application

9.1 The PetSitter idea

9.2 PetSitter project kickoff

9.2.1 Additional requirements

9.2.2 Team structure

9.2.3 API-driven architecture

9.2.4 The plan

9.3 Domain Modeling and APIs

9.3.1 General Introduction

9.3.2 Domain modeling for APIs

9.3.3 Looking back on FarmStall

9.4 A domain model for PetSitter

9.4.1 Concepts in the model

9.4.2 The user model

9.4.3 The job and dog models

9.5 User stories for PetSitter

9.5.1 What are user stories?

9.5.2 Collecting user stories

9.5.3 Mapping user stories

9.6 Summary

10 Creating an API design using OpenAPI

10.1 The problem

10.1.1 Converting a domain model into OpenAPI

10.1.2 Ensuring reusability

10.2 Creating the schemas

10.2.1 Starting an OpenAPI file with schemas

10.2.2 Referencing common schemas

10.2.3 The User schema

10.2.4 The Job schema

10.2.5 The Dog schema

10.2.6 The Job Application schema

10.3 The CRUD approach to API operations

10.3.1 Defining API requests and responses

10.3.2 From user stories to CRUD design

10.4 API operations for PetSitter

10.4.1 User operations

10.4.2 Job operations

10.4.3 Job Application operations

10.5 Summary

Part 2

11 Building a change workflow around API Design First

12 Implementing frontend code and reacting to changes

13 Building a backend with Node.js and Swagger Codegen

14 Integrating and releasing the web application

15 Reviewing our plan and design strategy

Part 3

16 Designing the next API iteration

17 Versioning an API and handling breaking changes

18 Scaling collection endpoints with filters and pagination

19 Supporting the unhappy path: error handling with problem+json

20 Improving input validation with advanced JSON Schema

21 Beyond the application: what’s next for our API?

Part 4

22 Composition of API definitions

23 Swagger 2.0 vs OpenAPI 3.0 vs OpenAPI 3.1

24 Building your own tools for OpenAPI

25 Enter OAuth: Securing an API for public usage

26 Deploying an API Gateway

27 Using OpenAPI for API testing and monitoring

What's inside

  • OpenAPI syntax and structure
  • Using Swagger and OSS tooling to create OpenAPI definitions
  • Automating processes and generating code
  • Working with cross-functional teams

About the reader

Web developers who need to build APIs for their teams and customers.

About the authors

Josh Ponelat is a senior architect working with the Swagger/OpenAPI team at SmartBear. He’s based out of Plettenberg Bay, South Africa with his two labradors.

Lukas Rosenstock is an independent software developer, technical writer, API consultant, and entrepreneur who has a decade of experience working in and with startups.

placing your order...

Don't refresh or navigate away from the page.
Manning Early Access Program (MEAP) Read chapters as they are written, get the finished eBook as soon as it’s ready, and receive the pBook long before it's in bookstores.
print book $29.99 $59.99 pBook + eBook + liveBook
Additional shipping charges may apply
Designing APIs with Swagger and OpenAPI (print book) added to cart
continue shopping
go to cart

eBook $24.99 $47.99 3 formats + liveBook
Designing APIs with Swagger and OpenAPI (eBook) added to cart
continue shopping
go to cart

Prices displayed in rupees will be charged in USD when you check out.

FREE domestic shipping on three or more pBooks