BOOKSEEK BOOK NOTES
OpenAPI와 스웨거를 활용한 실전 API 설계
API 계약을 OpenAPI 문서로 표현하고 설계 단계에서 검토하려는 독자를 위한 책입니다. 요청·응답·스키마에서 문서화와 테스트, 변경까지 이어지는 흐름을 살피며, 설계 원칙을 구체적인 명세로 옮기는 학습 방법을 안내합니다.
이 포스팅은 쿠팡 파트너스 활동의 일환으로, 이에 따른 일정액의 수수료를 제공받습니다.
책의 기본 정보
- 출판사
- 책만
- 출간일
- 2024-01-02
- 분량
- 520쪽
- ISBN
- 9791189909581
책의 내용과 읽을 거리
『OpenAPI와 스웨거를 활용한 실전 API 설계』는 API에서 주고받을 약속을 구체적인 문서로 표현하려는 독자를 위한 책입니다. OpenAPI 정의와 요청·응답·스키마를 익히고, 설계를 먼저 검토하는 방식에서 문서화와 자동화, 테스트와 변경으로 나아갑니다. HTTP와 JSON의 기초를 알고 있지만 명세 파일을 구현 코드의 부록처럼만 다뤘던 개발자가 살펴볼 만합니다.
설계를 먼저 한다는 것은 구현을 시작하지 않고 문서만 오래 작성한다는 뜻으로 읽을 필요는 없습니다. API를 이용할 사람이 어떤 요청을 보내고 어떤 결과를 기대할 수 있는지 먼저 합의하는 과정으로 생각해 보세요. 이 책은 그 약속을 OpenAPI로 표현하는 범위를 제공합니다. 자신의 연습용 API 하나를 고른 뒤 구현 언어를 떠나 요청과 응답을 설명할 수 있는지 확인하는 활동이 좋습니다.
경로와 작업, 매개변수와 응답을 작성할 때는 문법이 맞는지만 확인하지 마세요. 각 항목이 API 사용자에게 무엇을 알려 주는지 읽어 보세요. 같은 정보가 여러 곳에 서로 다르게 적혀 있거나 필수 조건이 모호하면 명세 파일을 작성했다는 사실만으로 계약이 명확해지지 않습니다. 책의 예제를 활용해 실제 요청 하나를 보내는 사람의 입장에서 필요한 정보가 모두 있는지 살펴볼 수 있습니다.
스키마는 데이터의 모양을 표현하는 범위이지만 업무상의 의미를 모두 자동으로 결정해 주지는 않습니다. 어떤 값이 필요한지, 비어 있을 수 있는지, 요청과 응답에서 역할이 같은지 질문해 보세요. 예제의 필드를 자신의 연습 데이터로 바꿀 때도 이름만 교체하기보다 의미와 조건을 함께 적는 편이 좋습니다. 데이터 구조를 문서로 옮기는 과정에서 설계의 빈틈을 발견하는 것이 중요한 학습 목표입니다.
문서 생성과 도구 활용, 테스트로 이어지는 부분은 하나의 정의를 여러 작업에서 사용하는 흐름을 보여 줍니다. 자동으로 문서가 만들어진다는 사실과 설명이 충분하다는 사실은 구분해야 합니다. 테스트 역시 어떤 계약을 확인하는지 먼저 명시해야 결과를 해석할 수 있습니다. 책을 읽으며 자동화되는 부분과 사람이 검토해야 할 부분을 나누어 적으면 도구에 기대할 범위가 선명해집니다.
API의 생애주기와 변경을 살피는 범위에서는 이미 만들어진 계약을 수정할 때 무엇을 확인할지 생각해 볼 수 있습니다. 필드를 하나 추가하거나 응답 구조를 바꾸는 작은 연습을 정하고, 기존 사용자에게 어떤 영향이 생길지 검토해 보세요. 한국어판에는 Spring Boot 관련 부록도 포함되지만 이를 모든 프레임워크를 다루는 종합 구현서로 볼 필요는 없습니다. 중심은 설계와 명세, 도구를 연결하는 과정입니다.
소개하는 것은 2024년 한국어 종이책이며 목차에서 다루는 OpenAPI 버전 범위는 3.0.x입니다. 이를 이후 명세 버전이나 현재 도구의 모든 동작과 동일하게 받아들이지 마세요. 문서의 구조와 설계 과정을 익힌 뒤 실제 프로젝트가 사용하는 버전과 플러그인 조건을 확인하는 편이 좋습니다. 설계 원칙만 읽는 책보다 직접 계약을 작성하고 검토할 일이 있는 독자에게 가까운 선택입니다.
이 책에서 공부할 수 있는 내용
OpenAPI의 경로·요청·응답·스키마를 작성하고 설계를 먼저 검토하는 과정을 공부할 수 있습니다. 문서화·자동화·테스트와 API의 변경도 다룹니다. 활용 질문은 명세만 읽고 요청을 만들 수 있는지, 데이터의 조건이 모호하지 않은지, 계약을 수정하면 기존 사용자가 무엇을 바꾸어야 하는지입니다.
설명 방식에서 눈여겨볼 특징
- 계약을 구체화하는 문서: 요청·응답·스키마를 OpenAPI로 표현합니다.
- 설계 우선의 흐름: 구현 전에 사용자가 기대할 동작을 검토하는 과정입니다.
- 도구와 검토의 연결: 문서 생성과 테스트를 설계의 확인 과정에 활용합니다.
- 변경을 고려한 작성: API 계약을 수정할 때 생기는 영향을 살핍니다.
- 판본의 기술 범위: OpenAPI 3.0.x와 한국어판의 Spring Boot 부록을 구분해 소개합니다.
이런 독자에게 권합니다
HTTP와 JSON을 이해하고 API 명세를 처음 작성하거나 팀의 계약 문서를 정리하려는 개발자에게 권합니다. 경로와 스키마를 실제로 작성하며 배우는 편이 맞는 독자에게 적합합니다. 업무 경계부터 다시 정해야 하는 상황이라면 설계 원칙 중심 책과 함께 비교하세요.
이 책에서 주로 다루는 내용
- OpenAPI로 요청·응답·스키마 표현
- 설계 우선 방식과 도구의 활용
- 계약 검증과 API 변경 관리
작가 소개
조시 포널랫은 Swagger 오픈소스 관련 업무에, 루카스 로젠스톡은 API 생애주기 관련 컨설팅·개발·기술 문서 작업에 참여해 왔습니다. 책만의 저자 소개에서 두 저자의 API 도구 및 문서화 경험을 확인할 수 있습니다.