[Part 1] Describing an Existing Product's API in OpenAPI Format

Chapter 1: Introduction to API and OpenAPI
__1.1 What is the API ecosystem?
__1.2 Describing the API
____1.2.1 Bridget's Work
____1.2.2 The Potential of Bridget's Solution
__1.3 What is OpenAPI?
____1.3.1 OpenAPI Definition Example
__1.4 Where is it best to use the OpenAPI definition?
__1.5 What is Swagger?
__1.6 What is REST?
__1.7 When to use OpenAPI?
____1.7.1 API Users
____1.7.2 API Provider
____1.7.3 API Designer
__1.8 Structure of this book
__1.9 Summary

Chapter 2: Preparing API Requests
__2.1 Problem Definition
____2.1.1 Direct Sales API Overview
____2.1.2 The first two operations of the Direct Sales API
__2.2 Postman Preparation
__2.3 Direct Sales API
__2.4 View review list
____2.4.1 Configuring a GET Request
____2.4.2 Check
__2.5 Leave a review
____2.5.1 Configuring a POST Request
____2.5.2 Check
__2.6 Practice
____2.6.1 The Truth About Cats API
____2.6.2 Minimal Avatar API
____2.6.3 DuckDuckGo Search Engine API
____2.6.4 Pirate Slang API
__2.7 HTTP for Warriors
__2.8 Summary

Chapter 3: First Impressions of the OpenAPI Definition
__3.1 Problem Definition
__3.2 Introduction to the OpenAPI Specification
__3.3 YAML Overview
___3.3.1 JSON to YAML
__3.4 Describing the GET operation
__3.5 GET operation extension
__3.6 Summary

Chapter 4: Creating an OpenAPI Definition with the Swagger Editor
__4.1 Introducing the Swagger Editor
___4.1.1 Editor Panel
___4.1.2 UI Documentation Panel
___4.1.3 Tools Menu
___4.1.4 Save
__4.2 Creating an OpenAPI definition in the Swagger editor
___4.2.1 Valid Mini OpenAPI Definition
___4.2.2 Creating an OpenAPI Definition in the Swagger Editor
___4.2.3 Verification
__4.3 Added GET /reviews
__4.4 API Calls
___4.4.1 Calling GET /reviews
___4.4.2 Adding server information to the OpenAPI definition
___4.4.3 Call GET /reviews again
__4.5 Summary

Chapter 5: Describing API Responses
__5.1 HTTP response
__5.2 Problem Definition
__5.3 The Amazing World of Data Schemas
__5.4 JSON Schema
___5.4.1 type field
___5.4.2 Adding fields to an object
___5.4.3 minimum and maximum
___5.4.4 Number and Integer
__5.5 Status Code
__5.6 Media Type (MIME)
__5.7 Describing the GET /reviews Response
___5.7.1 Super Mini Response
___5.7.2 GET /reviews 200 Response Body
___5.7.3 Add a rating field to the response body
___5.7.4 Add message, uuid, and userId fields
__5.8 Summary

Chapter 6: Resource Creation
__6.1 Problem Definition
__6.2 Describing POST /reviews and the Request Body
___6.2.1 Request Body
___6.2.2 Schema of requestBody
__6.3 Create a new review
___6.3.1 Improved try-it-out functionality with additional examples
__6.4 Describing GET /reviews/{reviewId} with path parameters
___6.4.1 Path Parameters
___6.4.2 Describing the reviewId path parameter
__6.5 Confirm creation of review
__6.6 Summary

Chapter 7 Authentication and Authorization
__7.1 Problem Definition
__7.2 Preparing for Certification
___7.2.1 Challenge: Writing a POST /users
___7.2.2 Challenge: Writing a POST /tokens
___7.2.3 Solution: Change the definition
___7.2.4 Verify user and token creation capabilities
__7.3 Adding Authorization header
___7.3.1 OpenAPI authorization processing method
___7.3.2 Authorization (Security) Methods Supported by OpenAPI 3.0.x
___7.3.3 Adding an Authorization header to the security scheme
___7.3.4 Add security requirements to POST /reviews
___7.3.5 Verifying Security Function Operation
__7.4 Optionally apply security
__7.5 Other security schemes
__7.6 General Ways to Apply Security Schemes
__7.7 Summary

Chapter 8: Preparing and Hosting API Documentation
__8.1 Problem Definition
__8.2 Adding metadata to the API definition
__8.3 Writing descriptions in Markdown
___8.3.1 Markdown Basics
___8.3.2 Added Markdown description to the Direct Sales API definition
__8.4 Grouping operations with tags
___8.4.1 Adding tags to the GET /reviews operation
___8.4.2 Add a description to the tag
___8.4.3 Adding tags to remainder operations
__8.5 Hosting API Documentation with Netlify.com and Swagger UI
___8.5.1 Preparing Swagger UI with OpenAPI Definition
___8.5.2 Hosted by Netlify.com
__8.6 Part 1 Conclusion
__8.7 Summary

[Part 2] API Design First Using OpenAPI and Swagger

Chapter 9: Web Application Design
__9.1 Pet Sitter Ideas
__9.2 Pet Sitter Project Launch
___9.2.1 Additional Requirements
___9.2.2 Team Structure
___9.2.3 API-centric architecture
___9.2.4 Plan
__9.3 Domain Modeling and API
___9.3.1 Domain Modeling for API Use
___9.3.2 Review of the Direct Sales API
__9.4 Pet Sitter Domain Model
___9.4.1 Concepts used in the model
___9.4.2 User Model
___9.4.3 Job Postings and Pet Models
__9.5 Pet Sitter User Story
___9.5.1 What is a User Story?
___9.5.2 Collecting User Stories
___9.5.3 User Story Mapping
__9.6 Summary

Chapter 10: API Design Using OpenAPI
__10.1 Problem
___10.1.1 Converting the domain model to OpenAPI
___10.1.2 Ensuring Reusability
__10.2 Creating a schema
___10.2.1 OpenAPI file containing the schema
___10.2.2 Common Schema Reference
___10.2.3 User Schema
___10.2.4 Job Schema
___10.2.5 Dog Schema
___10.2.6 JobApplication Schema
__10.3 API operations and CRUD
___10.3.1 Defining API Requests and Responses
___10.3.2 User Stories and CRUD Design
__10.4 Pet Sitter API
___10.4.1 Operations required for the User schema
___10.4.2 Operations required for the Job schema
___10.4.3 Operations required for the JobApplication schema
__10.5 Summary

Chapter 11: Building a Change Workflow with an API Design-First Approach
__11.1 Problem
__11.2 Change Discussion and Response
__11.3 GitHub as a Workflow Engine
___11.3.1 Single Source of Truth
___11.3.2 Change Proposal
___11.3.3 Accepting Changes
___11.3.4 Check Change Comparison
__11.4 GitHub Workflow Integration
___11.4.1 Configuring GitHub and the Source of Truth
___11.4.2 GitHub Workflow Steps
__11.5 Workflow Practice
___11.5.1 Added suggestion to DELETE /jobs/{id}
___11.5.2 Review and Accept Changes
___11.5.3 Comparing Old and New Branches
___11.5.4 What we did in Chapter 11
__11.6 Summary

Chapter 12: Implementing Front-End Code and Responding to Changes
__12.1 Problem
__12.2 Prism Neck Server Configuration
___12.2.1 Prism Installation
___12.2.2 Checking Prism Operation
__12.3 Front-end development based on the wooden server
___12.3.1 Adding examples to the OpenAPI definition
___12.3.2 Applying examples to prisms
__12.4 Identifying Missing API Operations
___12.4.1 Review Adding New Operations
___12.4.2 New Operation Design
___12.4.3 Selecting the neck data to be returned from the prism
___12.4.4 Change Proposal
___12.4.5 curl example
__12.5 Summary

Chapter 13: Building a Backend with Node.js and Swagger CodeGen
__13.1 Problem
__13.2 Introducing Swagger Codegen
___13.2.1 Generating Client Code
___13.2.2 Generating Server Code
___13.2.3 Swagger Generator
__13.3 Backend Structure
___13.3.1 Generating Backend Code
___13.3.2 Backend Structure Analysis
___13.3.3 OpenAPI Modifications
__13.4 Backend OpenAPI modification
___13.4.1 Add operation ID
___13.4.2 Tagging API Operations
___13.4.3 Regenerating the Backend Stubs
__13.5 Running and Testing Backend Code
___13.5.1 Testing with Postman
___13.5.2 Input Validation Test
___13.5.3 Verifying results with a prism
__13.6 Saving a database with Mongoose
___13.6.1 API fixes
___13.6.2 Preparing to Use MongoDB
___13.6.3 Mongoose Configuration
___13.6.4 Creating a Model
__13.7 Implementing API Methods
__13.8 Summary

Chapter 14: Integrating and Deploying Web Applications
__14.1 Problem
___14.1.1 Authentication
___14.1.2 Code Organization
___14.1.3 Providing backend and frontend components together
__14.2 Authorization Implementation
___14.2.1 Creating a Security Scheme
___14.2.2 Added 'Login' action
___14.2.3 Defining Operational Security
__14.3 Repository Management
___14.3.1 Maintaining the existing structure
___14.3.2 Using a Shared Git Repository
___14.3.3 Consolidating code and API definitions into a single repository
___14.3.4 Decisions and Refactoring
__14.4 Configuring the Integrated Web Server
___14.4.1 URL Design
___14.4.2 Server Configuration
__14.5 Summary

[Part 3] API Expansion and Evolution After Product Launch

Chapter 15: Secondary API Design
__15.1 First Development Sprint Review
__15.2 Next Sprint Planning
__15.3 Preparing new features
___15.3.1 Revisiting the Domain Model
___15.3.2 User Story Review
__15.4 Developer Experience Improvements
___15.4.1 Consistency
___15.4.2 Error Handling
___15.4.3 Input Validation
___15.4.4 Versioning and Evolution
__15.5 Summary

Chapter 16 Schema Design Using OpenAPI Composition
__16.1 Problem
__16.2 Domain Model Polymorphism and Inheritance
__16.3 Schema Update
___16.3.1 Pet Schema
___16.3.2 Dog Schema
___16.3.3 Cat Schema
__16.4 Polymorphism and Inheritance in OpenAPI
___16.4.1 Composition within the Dog and Cat schemas
___16.4.2 Composition within the Pet schema
__16.5 Add OpenAPI delimiter
__16.6 Summary

Chapter 17 Applying Filters and Paging to Collection Endpoints
__17.1 Problem
__17.2 Filtering Design
___17.2.1 Projection Filter
___17.2.2 Selection Filter
___17.2.3 Handling Nested Schemas
___17.2.4 Query Language
___17.2.5 Special Practices
__17.3 Pet Sitter Filtering
___17.3.1 Selecting the filtering criteria field
___17.3.2 Applying Filtering to OpenAPI
___17.3.3 Request to include filters
__17.4 Paging Design
___17.4.1 Offset-based, page-based paging
___17.4.2 Cursor-based paging
__17.5 Applying paging to pet sitters
___17.5.1 Applying Paging to OpenAPI
___17.5.2 Extending the Request Example
__17.6 Sorting Design
___17.6.1 Single Field Sorting
___17.6.2 Multi-field sorting
___17.6.3 Parameter Type Consistency
__17.7 Applying sorting to pet sitters
___17.7.1 Sort Fields
___17.7.2 Design of sorting parameters
___17.7.3 Add sorting functionality to the OpenAPI definition
___17.7.4 Example request with filtering, paging, and sorting
__17.8 Summary

Chapter 18: Exception Handling Using Problem+Json
__18.1 Problem Definition
__18.2 Error Classification
___18.2.1 Finding Failure Situations
___18.2.2 Common Error Patterns
__18.3 Error Response Requirements
__18.4 OAS Tool Format
__18.5 problem+json format
__18.6 Adding error responses to the OpenAPI definition
___18.6.1 Creating an Error Schema
___18.6.2 Add error response to operations
__18.7 Error Handling Guide
___18.7.1 Front-end development
___18.7.2 Backend Development
__18.8 Summary

Chapter 19: Input Validation Using Advanced JSON Schema
__19.1 Problem Definition
__19.2 Validation Details
___19.2.1 readOnly, writeOnly properties
___19.2.2 Enforcing numeric constraints
___19.2.3 String format coercion
___19.2.4 Enforcing Array Constraints
___19.2.5 Enumeration Definition
___19.2.6 List of required and optional properties
___19.2.7 Specifying default values
__19.3 Pet Sitter Schema Update
___19.3.1 User Schema
___19.3.2 Job Schema
___19.3.3 JobApplication Schema
___19.3.4 Pet, Dog, Cat Schema
__19.4 Summary

Chapter 20: API Version Management and Handling Major Changes
__20.1 Problem Definition
__20.2 What is a major change?
__20.3 Major changes released
___20.3.1 Company Change Coordination
___20.3.2 API Version Management
___20.3.3 Distinguishing schema versions using media types
___20.3.4 Notice of addition/deletion of features
__20.4 Summary

Chapter 21: API Pre-Launch Checklist
__21.1 Pros and Cons of Public APIs
__21.2 Checklist
__21.3 API normal operation
___21.3.1 API Unit Tests
___21.3.2 End-to-end testing
__21.4 Documentation
__21.5 Ensuring API Consistency
__21.6 Validation and Error Reporting
__21.7 API Roadmap and Index Released
__21.8 Change Strategy
__21.9 Security Improvements
__21.10 API Monitoring
___21.10.1 Configuring Indicator Collection
__21.11 API Release
___21.12 Summary

Appendix A Swagger 2.0, OpenAPI 3.0, OpenAPI 3.1
Appendix B [Korean Special Appendix] How to Use Swagger in Spring Boot Web Services

What this book covers

This book covers how to describe and design APIs.
As an introductory guide to the world of OpenAPI, we explore the tools and practices used by API developers who practice design-first principles.
It starts with the basics of reading and writing OpenAPI definitions, and moves on to domain design, workflow changes, and API design patterns.
While we focus on OpenAPI and API design, we've tried to cover topics across the entire API lifecycle, from both technical and project management perspectives.
I hope this book will help you understand and gain confidence in what problems OpenAPI solves, why it exists, and how to use it.

- Describe the API of an existing product in OpenAPI format.
- Applying a design-first approach to API design using OpenAPI and Swagger.
- Learn how to expand and evolve your API after product launch.
- Learn OpenAPI syntax and structure.
- Create an OpenAPI definition using Swagger.
- Automate processes and automatically generate code.
- Learn how to collaborate across functional organizations.

Target audience for this book

This is a must-read for software developers who are interested in APIs and want to use them in a design-first manner.
A must-read for anyone who needs to make API-related decisions—front-end or back-end developers, product managers, QA testers, and even CEOs.
We've taken care to make the book accessible even if you don't have an in-depth understanding of any particular topic, and if you're familiar with concepts like JSON or HTTP, you should have no trouble following the book.
It also includes a lot of simple reviews and links to external resources.

Structure of this book

[Part 1] Describing an existing product's API in OpenAPI format
Chapter 1: The Meaning and Method of Describing APIs
· Chapter 2: Postman, a tool used to explore APIs
· Chapter 3: How to describe a pre-built Farmstall API
Chapter 4: How to Use the Swagger Editor
Chapter 5: Describing Basic API Requests and Responses
Chapter 6: Covering Request and Response Bodies
Chapter 7: Understanding Authentication and Authorization
Chapter 8: How to Host a Website That Serves API Documentation Using Swagger UI

[Part 2] Designing an API from Scratch Using OpenAPI and Swagger
Chapter 9: Introducing the PetSitter project, which will be covered throughout Part 2.
Chapter 10: Designing an API and Describing It Using OpenAPI
Chapter 11: Introducing a Git-based workflow for handling API design changes
Chapter 12: How to Mock Your API and Respond to Changes from an API User's Perspective
Chapter 13: Implementing an API Using Swagger CodeGen
Chapter 14: Preparing to use the API and integrating the frontend and backend

[Part 3] Expanding and Evolving the API Design Created in Part 2
Chapter 15: Planning the Next Steps of Your API Iteration
· Chapter 16: Extending the Domain Model Using JSON Schema Composition
Chapter 17: Adding Filtering, Paging, and Sorting to Your API
Chapter 18: Understanding the problem+json response format and applying error handling to APIs
Chapter 19: Extending JSON Schema and Applying Input Validation
Chapter 20: API Versioning and Handling Breaking Changes
Chapter 21: API Final Release Checklist

[Appendix] Differences between Swagger 2.0, OpenAPI 3.0, and OpenAPI 3.1
[Korean Edition Special Appendix] How to Use Swagger in Spring Boot Web Services

Author's Note

Swagger, a suite of tools to help you define and write REST API documentation, lets you provide highly usable, secure API documentation.
Swagger implements the OpenAPI specification, a standard that is independent of any specific company, so when you use Swagger, you're using the same standards accepted by Google, Microsoft, and Amazon.
This book introduces a design-first approach. Developers new to API design can learn the entire API lifecycle, from conceptualization to production level.
As you gradually complete examples, you'll learn the dos and don'ts of API design and development.
Gain hands-on experience designing APIs that meet your business needs using tools that automatically generate documentation and developer-friendly mocks or client SDKs.
Even if you are a web developer with no prior knowledge of Swagger or OpenAPI, you can easily read this.

Translator's Note

I remember back when the Internet was first introduced, there was an experiential entertainment content that tested how well you could get by with just the Internet without leaving your home.
But now, I don't think anyone will watch that kind of entertainment.
Because we all know that anyone with access to a smartphone can lead a comfortable life using only the Internet.
If we continue to zoom in on this convenient world, where we can receive and use items, have food delivered, and even brag about it all on social media with just a few swipes and clicks, we'll see APIs hidden in every nook and cranny. APIs serve as the connecting points between various software, solidly supporting this world.

APIs, which serve as a connecting point for software, serve as a means of communication for software developers.
To ensure smooth communication, we need to create a specification that defines the format of data to be exchanged and the method of calling, along with a friendly description of it.
That is, you need to describe the API.
OpenAPI is a standard specification that describes HTTP APIs based on the HTTP protocol. Since standards enable automation, many tasks can be automated through OpenAPI.
This book explains how to describe API definitions using OpenAPI.
If it had ended there, it might have been a boring book, but it covers everything from organizing the requirements of a small web service, writing user stories, designing a business domain model based on them, designing an API that reflects them, writing an API definition using OpenAPI, increasing development productivity using automation based on the definition, and even how to smoothly evolve and extend the API over time.

When designing APIs, there are many unfortunate cases in practice where people design and implement them only for convenience without any specific learning or standards, which makes it difficult to expand later. However, if you read the best practices in this book, you can naturally acquire the knowledge necessary to design scalable APIs. This content alone would be beneficial, but the entire process is unfolded in a format that depicts a small project team being formed, each performing their own role, encountering and solving difficulties, rather than a boring and stiff explanation, making it exciting and even fun.
Moreover, although it occasionally uses specific technologies for examples, it is not inherently tool-dependent, making it an interesting and useful book for all developers who create and utilize APIs.

The content of this book generally shows the process of designing and creating a new system using OpenAPI, so you might wonder if it can't be applied to existing systems. Fortunately, there is a way to apply it to existing systems as well.
If you are using Spring Boot-based API server, which is the most widely used API server development platform in Korea, you can automatically create a Swagger UI site with just a few simple settings and annotations.
Although it is a simple example, I thought it would be quite helpful in practice, so I added it as a special appendix to the Korean version.

Just like with coding, I always see room for improvement in translation.
The same would probably be true for the authors who wrote the original book.
A translator's primary job is to translate the original text into Korean, but I believe a great translator is someone who first reads the original text from the reader's perspective, identifies any inconvenient points, improves them, and ultimately presents a better result to the reader.
This time, too, there may be shortcomings, but I wanted to at least imitate the excellent translator, so I worked on the translation with the goal of making it better than the original.
I sincerely hope that readers will be able to read this book as fluently as if it were written in Korean from the beginning.