book

Designing APIs with Swagger and OpenAPI

by Lukas Rosenstock, Joshua Ponelat

June 2022

Intermediate to advanced

424 pages

11h 50m

English

Manning Publications

Read now

Unlock full access

forewordprefaceacknowledgmentsabout this bookWho should read this bookHow this book is organized: A roadmapAbout the codeliveBook discussion forumOther online resourcesabout the authorsabout the cover illustration
1.1 What is an API ecosystem?1.2 Describing things1.2.1 Bridget’s task1.2.2 The potential of Bridget’s solution1.3 What is OpenAPI?1.3.1 Example OpenAPI definition1.4 Where do OpenAPI definitions fit in?1.5 What is Swagger?1.6 What about REST?1.7 When to use OpenAPI1.7.1 For API consumers1.7.2 For API producers1.7.3 For API designers1.8 This bookSummary
2.1 The problem2.1.1 FarmStall API overview2.1.2 The first two operations of the FarmStall API2.2 Getting set up with Postman2.3 FarmStall API2.4 Our first request2.4.1 Forming a GET request in Postman2.4.2 Verification2.5 Adding a review to the FarmStall API2.5.1 Forming a POST request in Postman2.5.2 Verification2.6 Practice2.6.1 Cat (and other animal) facts API2.6.2 Random avatar API2.6.3 DuckDuckGo’s search engine API2.6.4 Pirate talk API2.7 HTTP for the braveSummary
3.1 The problem3.2 Introducing the OpenAPI specification3.3 A quick refresher on YAML3.3.1 From JSON to YAML3.4 Describing our first operation3.5 Extending our first operationSummary

4.1 Introducing Swagger Editor4.1.1 The Editor panel4.1.2 The UI Docs panel4.1.3 The toolbar4.1.4 Persistence4.2 Writing the smallest OpenAPI definition in Swagger Editor4.2.1 The smallest valid OpenAPI definition4.2.2 Writing in Swagger Editor4.2.3 A word on validation4.3 Adding GET /reviews to our definition4.4 Interacting with our API4.4.1 Executing GET /reviews4.4.2 Adding servers to our definition4.4.3 Executing GET /reviews (again)Summary
5.1 HTTP responses5.2 The problem5.3 The mind-blowing world of data schemas5.4 JSON Schema5.4.1 The type field5.4.2 Adding a field to an object5.4.3 The minimum and maximum keywords5.4.4 Number vs. integer5.5 Status codes5.6 Media types (aka MIME)5.7 Describing the GET /reviews response5.7.1 Smallest response in OpenAPI5.7.2 The GET /reviews 200 response body5.7.3 Adding the rating field to our response body5.7.4 Describing message, uuid, and userIdSummary
6.1 The problem6.2 Describing POST /reviews with a request body6.2.1 Where to find request bodies6.2.2 Describing the schema for POST /reviews requestBody6.3 Executing operations with request bodies6.3.1 Adding examples to make try-it-out look pretty6.4 Describing GET /reviews/{reviewId} with a path parameter6.4.1 Path parameters6.4.2 Describing the reviewId path parameter6.5 Verifying our reviews are getting createdSummary
7.1 The problem7.2 Getting set up for authentication7.2.1 Challenge: Describe POST /users7.2.2 Challenge: Describe POST /tokens7.2.3 Solution: Definition changes7.2.4 Verifying we can create users and get a token7.3 Adding the Authorization header7.3.1 How OpenAPI handles authorization7.3.2 Types of authorization (securities) supported in OpenAPI 3.0.x7.3.3 Adding the Authorization header security scheme7.3.4 Adding the security requirements to POST /reviews7.3.5 Using the security feature of try-it-out7.4 Optional security7.5 Other types of security schemas7.6 How to add security schemes in generalSummary
8.1 The problem8.2 Adding metadata to the definition8.3 Writing the description in Markdown8.3.1 Markdown basics8.3.2 Adding a rich text description to the FarmStall API definition8.4 Organizing operations with tags8.4.1 Adding the Reviews tag to GET /reviews8.4.2 Adding descriptions to tags8.4.3 Adding the rest of the tags8.5 Hosting our API documentation using Netlify.com and Swagger UI8.5.1 Preparing Swagger UI with our definition8.5.2 Hosting on Netlify.com8.6 The end of part 1Summary
9.1 The PetSitter idea9.2 PetSitter project kickoff9.2.1 Additional requirements9.2.2 Team structure9.2.3 API-driven architecture9.2.4 The plan9.3 Domain modeling and APIs9.3.1 Domain modeling for APIs9.3.2 Looking back on FarmStall9.4 A domain model for PetSitter9.4.1 Concepts in the model9.4.2 The User model9.4.3 The Job and Dog models9.5 User stories for PetSitter9.5.1 What are user stories?9.5.2 Collecting user stories9.5.3 Mapping user storiesSummary
10.1 The problem10.1.1 Converting a domain model to OpenAPI10.1.2 Ensuring reusability10.2 Creating the schemas10.2.1 Starting an OpenAPI file with schemas10.2.2 Referencing common schemas10.2.3 The User schema10.2.4 The Job schema10.2.5 The Dog schema10.2.6 The JobApplication schema10.3 The CRUD approach to API operations10.3.1 Defining API requests and responses10.3.2 From user stories to CRUD design10.4 API operations for PetSitter10.4.1 User operations10.4.2 Job operations10.4.3 JobApplication operationsSummary
11.1 The problem11.2 Communicating and reacting to change11.3 GitHub as our workflow engine11.3.1 A single source of truth11.3.2 Suggesting a change11.3.3 Agreeing on a change11.3.4 A way of viewing changes (based on an older version)11.4 Tying the GitHub workflow together11.4.1 Setting up GitHub and the source of truth11.4.2 Steps in our GitHub workflow11.5 A practical look at the workflow11.5.1 Creating and suggesting DELETE /jobs/{id}11.5.2 Reviewing and accepting changes11.5.3 Comparing older branches to the latest11.5.4 What we’ve doneSummary
12.1 The problem12.2 Setting up Prism12.2.1 Installing Prism12.2.2 Verifying that Prism works12.3 Building a frontend based on a mock server12.3.1 Adding multiple examples into your OpenAPI definition12.3.2 Using examples in Prism12.4 Identifying a missing API operation12.4.1 Due diligence for adding the operation12.4.2 Designing the new operation12.4.3 Choosing which mock data response to get from Prism12.4.4 Formalizing and suggesting the change12.4.5 Extra curl examplesSummary
13.1 The problem13.2 Introducing Swagger Codegen13.2.1 Client code generation13.2.2 Server code generation13.2.3 Swagger Generator13.3 The backend structure13.3.1 Generating the backend13.3.2 Investigating the structure13.3.3 OpenAPI changes13.4 Updating OpenAPI for the backend13.4.1 Adding operation IDs13.4.2 Tagging API operations13.4.3 Regenerating the backend stubs13.5 Running and testing the backend13.5.1 Testing with Postman13.5.2 Testing input validation13.5.3 Output validation with Prism13.6 Database persistence with Mongoose13.6.1 Another API modification13.6.2 Getting ready to use MongoDB13.6.3 Configuring Mongoose in the project13.6.4 Creating models13.7 Implementing API methodsSummary
14.1 The problems14.1.1 Authentication14.1.2 Organizing code14.1.3 Serving both components14.2 Implementing authorization14.2.1 Creating a security scheme14.2.2 Adding a “Login” action14.2.3 Defining operation security14.3 Managing repositories14.3.1 Keeping the existing structure14.3.2 Creating a shared Git repository to implement both components14.3.3 Combining code and API definition in a repository14.3.4 Making the choice and refactoring14.4 Setting up an integrated web server14.4.1 URL design14.4.2 Server setupSummary
15.1 Reviewing the first development sprint15.2 Planning the next sprint15.3 Preparing for new features15.3.1 Reviewing the domain model15.3.2 Reviewing user stories15.4 Improving the developer experience15.4.1 Consistency15.4.2 Error handling15.4.3 Input validation15.4.4 Versioning vs. evolvabilitySummary
16.1 The problem16.2 Polymorphism and inheritance in domain models16.3 Updating the schemas16.3.1 The Pet schema16.3.2 The Dog schema16.3.3 The Cat schema16.4 Polymorphism and inheritance in OpenAPI16.4.1 Composition inside the Dog and Cat schemas16.4.2 Composition inside the Pet schema16.5 Adding discriminators in OpenAPISummary
17.1 The problem17.2 Designing filters17.2.1 Projection filters17.2.2 Selection filters17.2.3 Handling nested schemas17.2.4 Query languages17.2.5 Special conventions17.3 Filters for PetSitter17.3.1 Finding filter fields17.3.2 Adding filters to OpenAPI17.3.3 Making a request17.4 Designing pagination17.4.1 Offset-based and page-based pagination17.4.2 Cursor-based pagination17.5 Pagination for PetSitter17.5.1 Adding pagination to OpenAPI17.5.2 Extending our request example17.6 Designing sorting17.6.1 Single-field sorting17.6.2 Multifield sorting17.6.3 Consistency throughout parameter types17.7 Sorting for PetSitter17.7.1 Finding sorting fields17.7.2 Designing the sort parameter17.7.3 Adding sorting to OpenAPI17.7.4 The final request exampleSummary
18.1 The problem18.2 Error categories18.2.1 Finding unhappy paths18.2.2 Common error patterns18.3 Requirements for error responses18.4 The OAS tools format18.5 The problem+json format18.6 Adding error responses to OpenAPI18.6.1 Creating error schemas18.6.2 Adding errors to operations18.7 Error-handling guidance18.7.1 Frontend development18.7.2 Backend developmentSummary
19.1 The problem19.2 Supported validations19.2.1 Read-only and write-only properties19.2.2 Enforcing number constraints19.2.3 Enforcing string formats19.2.4 Enforcing array constraints19.2.5 Defining enumerations19.2.6 Listing required and optional properties19.2.7 Setting defaults19.3 Updating PetSitter schemas19.3.1 User schema19.3.2 Job schema19.3.3 JobApplication schema19.3.4 Pet, Dog, and Cat schemasSummary
20.1 The problem20.2 What is a breaking change?20.3 Releasing a breaking change20.3.1 Coordinated breaking changes20.3.2 Multiple API versions20.3.3 Using media types to version operations20.3.4 Adding and deprecating featuresSummary
21.1 Pros and cons of a public API21.2 The checklist21.3 Getting the API working21.3.1 Unit testing your API21.3.2 End-to-end testing21.4 Documentation21.5 Getting your API consistent21.6 Validation and error reporting21.7 An API roadmap and exposure index21.8 Getting a change strategy21.9 Improving security21.10 Monitoring your API21.10.1 Setting up metric collection21.11 Releasing the APISummary
A.1 The main differences between versionsA.2 OpenAPI 2.0 (Swagger 2.0)A.2.1 Non-changesA.2.2 host, basePath, and schemes → serversA.2.3 ResponsesA.2.4 parameter/in-body → requestBodyA.2.5 Components and structureA.2.6 anyOf, oneOfA.3 OpenAPI 3.1A.3.1 JSON Schema 2020-12A.3.2 VocabulariesA.3.3 OpenAPI extending JSON Schema (via a vocabulary)A.3.4 Webhooks

Content preview from Designing APIs with Swagger and OpenAPI

Part 1 Describing APIs

Before we start our journey into API design, we should get comfortable describing the existing world around us. Therefore, in part 1 we’ll look at how to describe an existing API using OpenAPI and Swagger. The API we’ll use, FarmStall, is hosted online and was created specifically for this book. It’s a little contrived but functional.

Chapter 1 will start by discussing the fundamentals of APIs and what OpenAPI is, provide a refresher on YAML, and go through each step that would lead up to a fully described API. We’ll then introduce tools like Postman (chapter 2) and Swagger Editor (chapter 4), and end up hosting a real API documentation website with Swagger UI (chapter 8). Areas of the API we’ll describe include requests ...