Designing APIs with Swagger and OpenAPI

Designing APIs with Swagger and OpenAPI

by Lukas Rosenstock, Joshua Ponelat
Released June 2022
Publisher(s): Manning Publications
ISBN: 9781617296284

Read it now on the O’Reilly learning platform with a 10-day free trial.

O’Reilly members get unlimited access to books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.

Start your free trial

Book description

Follow real-world API projects from concept to production, and learn hands-on how to describe and design APIs using OpenAPI.

In Designing APIs with Swagger and OpenAPI you will learn how to:

  • Understand OpenAPI syntax and structure
  • Use Swagger and other tooling to create OpenAPI definitions
  • Design authentication and authorization
  • Turn an OpenAPI description into online documentation
  • Automate processes and generating code
  • Iterate an API design with user stories
  • Build a frontend against a mock server
  • Generate backend code with Swagger Codegen
  • Versioning an API and dodging breaking changes
  • Work with cross-functional teams
Designing APIs with Swagger and OpenAPI is a comprehensive guide to designing and describing your first RESTful API using the most widely adopted standards. Following expert instruction from Swagger core contributor Josh Ponelat and API consultant Lukas Rosenstock, you’ll spend each chapter progressively expanding the kind of APIs you’ll want to build in the real world. You’ll utilize OpenAPI and Swagger to help automate your workflow, and free up your time to work on more exciting features. Learn the syntax and structure of OpenAPI definitions, create and iterate on an API design with common tools, and release your API to the public.

About the Technology
Create web APIs that customers and developers will love! Using Swagger, a collection of tools for defining and documenting REST APIs, you will build safe, controlled access to your software. And because Swagger implements the vendor-neutral OpenAPI specification, you’ll be building to the same standards adopted by Google, Microsoft, and Amazon.

About the Book
Designing APIs with Swagger and OpenAPI introduces a design-first approach. Written for developers new to API design, it follows the lifecycle of an API project from concept to production. You’ll explore the dos and don’ts of APIs through progressively complete examples. You’ll get hands-on experience designing APIs for specific business needs, using open source tools to generate documentation, and building developer-friendly components like mocks and client SDKs.

What's Inside
  • OpenAPI syntax and structure
  • Using Swagger to create OpenAPI definitions
  • Automating processes and generating code
  • Working with cross-functional teams


About the Reader
For web developers. No prior knowledge of Swagger or OpenAPI required.

About the Authors
Josh Ponelat is the Swagger Open Source lead at SmartBear. Lukas Rosenstock is an independent software developer and API consultant.

Quotes
This book clearly presents patterns and techniques that will enhance the experience for all software developers who need to work with APIs!
- From the Foreword by Tony Tam, Founder of Swagger

Everyone in the business of designing APIs should read this book!
- Pierre-Michel Ansel, 8x8

Essential advice for design-first API development.
- Ian Lovell, Cutover

A must-read for individuals and teams that are building APIs.
- Foster Haines, Senior Consultant at J2 Interactive

Table of contents

  1. inside front cover
  2. Designing APIs with Swagger and OpenAPI
  3. Copyright
  4. dedication
  5. contents
  6. front matter
    1. foreword
    2. preface
    3. acknowledgments
    4. about this book
      1. Who should read this book
      2. How this book is organized: A roadmap
      3. About the code
      4. liveBook discussion forum
      5. Other online resources
    5. about the authors
    6. about the cover illustration
  7. Part 1 Describing APIs
  8. 1 Introducing APIs and OpenAPI
    1. 1.1 What is an API ecosystem?
    2. 1.2 Describing things
      1. 1.2.1 Bridget’s task
      2. 1.2.2 The potential of Bridget’s solution
    3. 1.3 What is OpenAPI?
      1. 1.3.1 Example OpenAPI definition
    4. 1.4 Where do OpenAPI definitions fit in?
    5. 1.5 What is Swagger?
    6. 1.6 What about REST?
    7. 1.7 When to use OpenAPI
      1. 1.7.1 For API consumers
      2. 1.7.2 For API producers
      3. 1.7.3 For API designers
    8. 1.8 This book
    9. Summary
  9. 2 Getting set up to make API requests
    1. 2.1 The problem
      1. 2.1.1 FarmStall API overview
      2. 2.1.2 The first two operations of the FarmStall API
    2. 2.2 Getting set up with Postman
    3. 2.3 FarmStall API
    4. 2.4 Our first request
      1. 2.4.1 Forming a GET request in Postman
      2. 2.4.2 Verification
    5. 2.5 Adding a review to the FarmStall API
      1. 2.5.1 Forming a POST request in Postman
      2. 2.5.2 Verification
    6. 2.6 Practice
      1. 2.6.1 Cat (and other animal) facts API
      2. 2.6.2 Random avatar API
      3. 2.6.3 DuckDuckGo’s search engine API
      4. 2.6.4 Pirate talk API
    7. 2.7 HTTP for the brave
    8. Summary
  10. 3 Our first taste of OpenAPI definitions
    1. 3.1 The problem
    2. 3.2 Introducing the OpenAPI specification
    3. 3.3 A quick refresher on YAML
      1. 3.3.1 From JSON to YAML
    4. 3.4 Describing our first operation
    5. 3.5 Extending our first operation
    6. Summary
  11. 4 Using Swagger Editor to write OpenAPI definitions
    1. 4.1 Introducing Swagger Editor
      1. 4.1.1 The Editor panel
      2. 4.1.2 The UI Docs panel
      3. 4.1.3 The toolbar
      4. 4.1.4 Persistence
    2. 4.2 Writing the smallest OpenAPI definition in Swagger Editor
      1. 4.2.1 The smallest valid OpenAPI definition
      2. 4.2.2 Writing in Swagger Editor
      3. 4.2.3 A word on validation
    3. 4.3 Adding GET /reviews to our definition
    4. 4.4 Interacting with our API
      1. 4.4.1 Executing GET /reviews
      2. 4.4.2 Adding servers to our definition
      3. 4.4.3 Executing GET /reviews (again)
    5. Summary
  12. 5 Describing API responses
    1. 5.1 HTTP responses
    2. 5.2 The problem
    3. 5.3 The mind-blowing world of data schemas
    4. 5.4 JSON Schema
      1. 5.4.1 The type field
      2. 5.4.2 Adding a field to an object
      3. 5.4.3 The minimum and maximum keywords
      4. 5.4.4 Number vs. integer
    5. 5.5 Status codes
    6. 5.6 Media types (aka MIME)
    7. 5.7 Describing the GET /reviews response
      1. 5.7.1 Smallest response in OpenAPI
      2. 5.7.2 The GET /reviews 200 response body
      3. 5.7.3 Adding the rating field to our response body
      4. 5.7.4 Describing message, uuid, and userId
    8. Summary
  13. 6 Creating resources
    1. 6.1 The problem
    2. 6.2 Describing POST /reviews with a request body
      1. 6.2.1 Where to find request bodies
      2. 6.2.2 Describing the schema for POST /reviews requestBody
    3. 6.3 Executing operations with request bodies
      1. 6.3.1 Adding examples to make try-it-out look pretty
    4. 6.4 Describing GET /reviews/{reviewId} with a path parameter
      1. 6.4.1 Path parameters
      2. 6.4.2 Describing the reviewId path parameter
    5. 6.5 Verifying our reviews are getting created
    6. Summary
  14. 7 Adding authentication and authorization
    1. 7.1 The problem
    2. 7.2 Getting set up for authentication
      1. 7.2.1 Challenge: Describe POST /users
      2. 7.2.2 Challenge: Describe POST /tokens
      3. 7.2.3 Solution: Definition changes
      4. 7.2.4 Verifying we can create users and get a token
    3. 7.3 Adding the Authorization header
      1. 7.3.1 How OpenAPI handles authorization
      2. 7.3.2 Types of authorization (securities) supported in OpenAPI 3.0.x
      3. 7.3.3 Adding the Authorization header security scheme
      4. 7.3.4 Adding the security requirements to POST /reviews
      5. 7.3.5 Using the security feature of try-it-out
    4. 7.4 Optional security
    5. 7.5 Other types of security schemas
    6. 7.6 How to add security schemes in general
    7. Summary
  15. 8 Preparing and hosting API documentation
    1. 8.1 The problem
    2. 8.2 Adding metadata to the definition
    3. 8.3 Writing the description in Markdown
      1. 8.3.1 Markdown basics
      2. 8.3.2 Adding a rich text description to the FarmStall API definition
    4. 8.4 Organizing operations with tags
      1. 8.4.1 Adding the Reviews tag to GET /reviews
      2. 8.4.2 Adding descriptions to tags
      3. 8.4.3 Adding the rest of the tags
    5. 8.5 Hosting our API documentation using Netlify.com and Swagger UI
      1. 8.5.1 Preparing Swagger UI with our definition
      2. 8.5.2 Hosting on Netlify.com
    6. 8.6 The end of part 1
    7. Summary
  16. Part 2 Design-first
  17. 9 Designing a web application
    1. 9.1 The PetSitter idea
    2. 9.2 PetSitter project kickoff
      1. 9.2.1 Additional requirements
      2. 9.2.2 Team structure
      3. 9.2.3 API-driven architecture
      4. 9.2.4 The plan
    3. 9.3 Domain modeling and APIs
      1. 9.3.1 Domain modeling for APIs
      2. 9.3.2 Looking back on FarmStall
    4. 9.4 A domain model for PetSitter
      1. 9.4.1 Concepts in the model
      2. 9.4.2 The User model
      3. 9.4.3 The Job and Dog models
    5. 9.5 User stories for PetSitter
      1. 9.5.1 What are user stories?
      2. 9.5.2 Collecting user stories
      3. 9.5.3 Mapping user stories
    6. Summary
  18. 10 Creating an API design using OpenAPI
    1. 10.1 The problem
      1. 10.1.1 Converting a domain model to OpenAPI
      2. 10.1.2 Ensuring reusability
    2. 10.2 Creating the schemas
      1. 10.2.1 Starting an OpenAPI file with schemas
      2. 10.2.2 Referencing common schemas
      3. 10.2.3 The User schema
      4. 10.2.4 The Job schema
      5. 10.2.5 The Dog schema
      6. 10.2.6 The JobApplication schema
    3. 10.3 The CRUD approach to API operations
      1. 10.3.1 Defining API requests and responses
      2. 10.3.2 From user stories to CRUD design
    4. 10.4 API operations for PetSitter
      1. 10.4.1 User operations
      2. 10.4.2 Job operations
      3. 10.4.3 JobApplication operations
    5. Summary
  19. 11 Building a change workflow around API design-first
    1. 11.1 The problem
    2. 11.2 Communicating and reacting to change
    3. 11.3 GitHub as our workflow engine
      1. 11.3.1 A single source of truth
      2. 11.3.2 Suggesting a change
      3. 11.3.3 Agreeing on a change
      4. 11.3.4 A way of viewing changes (based on an older version)
    4. 11.4 Tying the GitHub workflow together
      1. 11.4.1 Setting up GitHub and the source of truth
      2. 11.4.2 Steps in our GitHub workflow
    5. 11.5 A practical look at the workflow
      1. 11.5.1 Creating and suggesting DELETE /jobs/{id}
      2. 11.5.2 Reviewing and accepting changes
      3. 11.5.3 Comparing older branches to the latest
      4. 11.5.4 What we’ve done
    6. Summary
  20. 12 Implementing frontend code and reacting to changes
    1. 12.1 The problem
    2. 12.2 Setting up Prism
      1. 12.2.1 Installing Prism
      2. 12.2.2 Verifying that Prism works
    3. 12.3 Building a frontend based on a mock server
      1. 12.3.1 Adding multiple examples into your OpenAPI definition
      2. 12.3.2 Using examples in Prism
    4. 12.4 Identifying a missing API operation
      1. 12.4.1 Due diligence for adding the operation
      2. 12.4.2 Designing the new operation
      3. 12.4.3 Choosing which mock data response to get from Prism
      4. 12.4.4 Formalizing and suggesting the change
      5. 12.4.5 Extra curl examples
    5. Summary
  21. 13 Building a backend with Node.js and Swagger Codegen
    1. 13.1 The problem
    2. 13.2 Introducing Swagger Codegen
      1. 13.2.1 Client code generation
      2. 13.2.2 Server code generation
      3. 13.2.3 Swagger Generator
    3. 13.3 The backend structure
      1. 13.3.1 Generating the backend
      2. 13.3.2 Investigating the structure
      3. 13.3.3 OpenAPI changes
    4. 13.4 Updating OpenAPI for the backend
      1. 13.4.1 Adding operation IDs
      2. 13.4.2 Tagging API operations
      3. 13.4.3 Regenerating the backend stubs
    5. 13.5 Running and testing the backend
      1. 13.5.1 Testing with Postman
      2. 13.5.2 Testing input validation
      3. 13.5.3 Output validation with Prism
    6. 13.6 Database persistence with Mongoose
      1. 13.6.1 Another API modification
      2. 13.6.2 Getting ready to use MongoDB
      3. 13.6.3 Configuring Mongoose in the project
      4. 13.6.4 Creating models
    7. 13.7 Implementing API methods
    8. Summary
  22. 14 Integrating and releasing the web application
    1. 14.1 The problems
      1. 14.1.1 Authentication
      2. 14.1.2 Organizing code
      3. 14.1.3 Serving both components
    2. 14.2 Implementing authorization
      1. 14.2.1 Creating a security scheme
      2. 14.2.2 Adding a “Login” action
      3. 14.2.3 Defining operation security
    3. 14.3 Managing repositories
      1. 14.3.1 Keeping the existing structure
      2. 14.3.2 Creating a shared Git repository to implement both components
      3. 14.3.3 Combining code and API definition in a repository
      4. 14.3.4 Making the choice and refactoring
    4. 14.4 Setting up an integrated web server
      1. 14.4.1 URL design
      2. 14.4.2 Server setup
    5. Summary
  23. Part 3 Extending APIs
  24. 15 Designing the next API iteration
    1. 15.1 Reviewing the first development sprint
    2. 15.2 Planning the next sprint
    3. 15.3 Preparing for new features
      1. 15.3.1 Reviewing the domain model
      2. 15.3.2 Reviewing user stories
    4. 15.4 Improving the developer experience
      1. 15.4.1 Consistency
      2. 15.4.2 Error handling
      3. 15.4.3 Input validation
      4. 15.4.4 Versioning vs. evolvability
    5. Summary
  25. 16 Designing schemas with composition in OpenAPI
    1. 16.1 The problem
    2. 16.2 Polymorphism and inheritance in domain models
    3. 16.3 Updating the schemas
      1. 16.3.1 The Pet schema
      2. 16.3.2 The Dog schema
      3. 16.3.3 The Cat schema
    4. 16.4 Polymorphism and inheritance in OpenAPI
      1. 16.4.1 Composition inside the Dog and Cat schemas
      2. 16.4.2 Composition inside the Pet schema
    5. 16.5 Adding discriminators in OpenAPI
    6. Summary
  26. 17 Scaling collection endpoints with filters and pagination
    1. 17.1 The problem
    2. 17.2 Designing filters
      1. 17.2.1 Projection filters
      2. 17.2.2 Selection filters
      3. 17.2.3 Handling nested schemas
      4. 17.2.4 Query languages
      5. 17.2.5 Special conventions
    3. 17.3 Filters for PetSitter
      1. 17.3.1 Finding filter fields
      2. 17.3.2 Adding filters to OpenAPI
      3. 17.3.3 Making a request
    4. 17.4 Designing pagination
      1. 17.4.1 Offset-based and page-based pagination
      2. 17.4.2 Cursor-based pagination
    5. 17.5 Pagination for PetSitter
      1. 17.5.1 Adding pagination to OpenAPI
      2. 17.5.2 Extending our request example
    6. 17.6 Designing sorting
      1. 17.6.1 Single-field sorting
      2. 17.6.2 Multifield sorting
      3. 17.6.3 Consistency throughout parameter types
    7. 17.7 Sorting for PetSitter
      1. 17.7.1 Finding sorting fields
      2. 17.7.2 Designing the sort parameter
      3. 17.7.3 Adding sorting to OpenAPI
      4. 17.7.4 The final request example
    8. Summary
  27. 18 Supporting the unhappy path: Error handling with problem+json
    1. 18.1 The problem
    2. 18.2 Error categories
      1. 18.2.1 Finding unhappy paths
      2. 18.2.2 Common error patterns
    3. 18.3 Requirements for error responses
    4. 18.4 The OAS tools format
    5. 18.5 The problem+json format
    6. 18.6 Adding error responses to OpenAPI
      1. 18.6.1 Creating error schemas
      2. 18.6.2 Adding errors to operations
    7. 18.7 Error-handling guidance
      1. 18.7.1 Frontend development
      2. 18.7.2 Backend development
    8. Summary
  28. 19 Improving input validation with advanced JSON Schema
    1. 19.1 The problem
    2. 19.2 Supported validations
      1. 19.2.1 Read-only and write-only properties
      2. 19.2.2 Enforcing number constraints
      3. 19.2.3 Enforcing string formats
      4. 19.2.4 Enforcing array constraints
      5. 19.2.5 Defining enumerations
      6. 19.2.6 Listing required and optional properties
      7. 19.2.7 Setting defaults
    3. 19.3 Updating PetSitter schemas
      1. 19.3.1 User schema
      2. 19.3.2 Job schema
      3. 19.3.3 JobApplication schema
      4. 19.3.4 Pet, Dog, and Cat schemas
    4. Summary
  29. 20 Versioning an API and handling breaking changes
    1. 20.1 The problem
    2. 20.2 What is a breaking change?
    3. 20.3 Releasing a breaking change
      1. 20.3.1 Coordinated breaking changes
      2. 20.3.2 Multiple API versions
      3. 20.3.3 Using media types to version operations
      4. 20.3.4 Adding and deprecating features
    4. Summary
  30. 21 The API prerelease checklist
    1. 21.1 Pros and cons of a public API
    2. 21.2 The checklist
    3. 21.3 Getting the API working
      1. 21.3.1 Unit testing your API
      2. 21.3.2 End-to-end testing
    4. 21.4 Documentation
    5. 21.5 Getting your API consistent
    6. 21.6 Validation and error reporting
    7. 21.7 An API roadmap and exposure index
    8. 21.8 Getting a change strategy
    9. 21.9 Improving security
    10. 21.10 Monitoring your API
      1. 21.10.1 Setting up metric collection
    11. 21.11 Releasing the API
    12. Summary
  31. Appendix A. Swagger 2.0, OpenAPI 3.0, and OpenAPI 3.1
    1. A.1 The main differences between versions
    2. A.2 OpenAPI 2.0 (Swagger 2.0)
      1. A.2.1 Non-changes
      2. A.2.2 host, basePath, and schemes → servers
      3. A.2.3 Responses
      4. A.2.4 parameter/in-body → requestBody
      5. A.2.5 Components and structure
      6. A.2.6 anyOf, oneOf
    3. A.3 OpenAPI 3.1
      1. A.3.1 JSON Schema 2020-12
      2. A.3.2 Vocabularies
      3. A.3.3 OpenAPI extending JSON Schema (via a vocabulary)
      4. A.3.4 Webhooks
  32. index
  33. inside back cover

Product information

  • Title: Designing APIs with Swagger and OpenAPI
  • Author(s): Lukas Rosenstock, Joshua Ponelat
  • Release date: June 2022
  • Publisher(s): Manning Publications
  • ISBN: 9781617296284