OpenAPI와 스웨거를 활용한 실전 API 설계

OpenAPI와 스웨거를 활용한 실전 API 설계

요구사항 분석부터 비즈니스 모델 설계, 문서화, 자동화, 테스트, API 확장과 진화까지 

조시 포널랫, 루카스 로젠스톡 지음 | 오명운 옮김
520쪽 | 35,000원 | 2024년 1월 2일 출간 | 185*240*25 | ISBN 9791189909581  (93000)

 

판매처 | [교보문고] [YES24] [알라딘] [영풍문고] [인터파크] + 전국 교보문고 매장
전자책 판매처 | [교보문고] [YES24] [알라딘] [리디북스] | 2024년 1월 31일 출간 | ISBN 9791189909598 | PDF 포맷

 

★ 정오표: https://www.onlybook.co.kr/entry/designing-API-errata 
★ 깃허브 예제코드 다운로드: 

• 직판장 API 소스 코드: https://github.com/designapis/farmstall (고(Go) 언어로 작성)
• 펫시터 API 소스 코드: https://github.com/designapis/petsitter (프론트엔드는 타입스크립트와 리액트로 작성, 백엔드는 스웨거 코드젠을 활용하여 자바스크립트로 작성)
• [한국어판 특별부록] 스프링 부트 앱에 스웨거 UI 입혀보는 예제 소스 코드: https://github.com/onlybooks/design-api
• 원서 <Designing APIs with Swagger and OpenAPI>  

 

스마트한 개발을 원하는 백엔드 개발자는 물론, 프로젝트 테크니컬 PM과 PO, 프론트엔드 개발자가 모두 함께 읽어야 할 필독서! 

요구사항 분석부터 사용자 스토리 작성, 고급 비즈니스 모델 설계, API 설계와 문서화, 자동화, 테스트, API의 확장과 진화까지, API 사용자와 개발자가 애용할 웹 API 설계와 활용에 대한 완벽 가이드! 

스프링 부트(Spring Boot) 웹서비스에 스웨거(Swagger)를 입혀 활용하는 방법을 알려주는 한국어판 특별부록 수록!

 

이 책은 API를 기술하고(describe) 설계하는(design) 방법을 다룬다. OpenAPI 세상으로 인도하는 입문서로서, 설계 우선 원칙을 실천하는 API 개발자가 사용하는 도구와 사례를 들여다본다. OpenAPI 정의서를 읽고 쓰는 기초부터 시작해서 도메인 설계, 워크플로 변경, API 디자인 패턴으로 나아간다. OpenAPI와 API 설계에 초점을 맞추지만 API 라이프사이클 전반에 걸친 주제를 모두 다루려고 노력했으며 기술 관점과 프로젝트 관리 관점을 두루 살펴볼 수 있다. OpenAPI가 어떤 문제를 해결해 주는지, 왜 존재하는지, 어떻게 사용하는지 이해하고 자신감을 갖는 데 이 책이 도움이 되었으면 한다.

- OpenAPI 형식으로 기존 제품의 API를 기술해 본다
- OpenAPI와 스웨거를 활용해 API 설계 우선 방식(design first approach)을 적용해 본다
- 제품 출시 이후 API 확장과 진화 방법을 알아본다
- OpenAPI 구문과 구조를 학습한다
- 스웨거를 사용해 OpenAPI 정의서를 생성한다
- 프로세스를 자동화하고 코드를 자동 생성해 본다
- 기능 조직 간 협업 방식을 배운다

 

이 책의 대상 독자
API에 흥미를 갖고 설계 우선 방식으로 API를 활용해 보려는 소프트웨어 개발자가 읽어야 하는 책이다. 프론트엔드 또는 백엔드 개발자, 제품 관리자, QA 테스터, 심지어 CEO까지 API 관련 의사결정을 내려야 하는 모두가 읽어야 한다. 특정 주제를 심도 깊이 이해하고 있지 않더라도 책을 읽을 수 있도록 주의를 기울였으며, JSON이나 HTTP 같은 개념에 익숙하다면 책을 읽는 데 아무런 문제가 없을 것이다. 또한 간단한 복습과 외부 자료에 대한 링크도 많이 담았다.

이 책의 구성 

[1부] OpenAPI 형식으로 기존 제품의 API를 기술해 보기
● 1장: API를 기술하는 의의와 방법
● 2장: API를 탐험하는 데 사용하는 도구인 포스트맨(Postman) 설명
● 3장: 이미 만들어져 있는 직판장(Farmstall) API를 기술하는 방법
● 4장: 스웨거 에디터 사용 방법
● 5장: 기본적인 API 요청과 응답 기술해 보기
● 6장: 요청 본문과 응답 본문 다뤄 보기
● 7장: 인증과 인가 알아보기
● 8장: 스웨거 UI를 사용해 API 문서를 제공하는 웹사이트를 호스팅하는 방법

[2부] 백지 상태에서 OpenAPI와 스웨거를 활용해 API를 설계해 보기
● 9장: 2부 전반에 걸쳐 다루게 될 펫시터(PetSitter) 프로젝트 소개
● 10장: API를 설계하고 OpenAPI를 사용해 API를 기술하는 과정
● 11장: API 설계 변경을 처리할 수 있는 깃(Git) 기반의 워크플로 소개
● 12장: API 사용자 입장에서 API에 대한 목(mock)을 활용하고 변경에 대응하는 방법
● 13장: 스웨거 코드젠을 사용해 API를 구현하는 방법
● 14장: API를 사용할 수 있도록 준비를 마치고 프론트엔드와 백엔드를 통합하는 과정

[3부] 2부에서 작성한 API 설계를 확장하고 진화시켜 보기
● 15장: 다음 단계의 API 반복(iteration)에 대한 계획 세우기
● 16장: JSON 스키마 합성(composition)을 사용한 도메인 모델 확장
● 17장: API에 필터링, 페이징, 정렬 기능 추가
● 18장: problem+json 응답 형식을 알아보고 API에 에러 처리 적용하기
● 19장: JSON 스키마를 확장하고 입력값 유효성 검증 적용하기
● 20장: API 버전 관리와 중대 변경(breaking change)을 처리하는 방법
● 21장: API 최종 출시 전 체크리스트

[부록] 스웨거 2.0, OpenAPI 3.0, OpenAPI 3.1의 차이점
[한국어판 특별부록] 스프링 부트 웹서비스에 스웨거를 입혀 활용하는 방법 

추천의 글

지난 10년간 소프트웨어 개발자의 직무는 급격하게 바뀌었다. 싱글 사인온(single sign-on), 퍼시스턴스(persistence), 장치 간 동기화, 공유 같은 기능이 표준화됐고 일상적인 기능인 것처럼 인식되고 있다. 소규모 점포의 경우 이처럼 필수적이지만 부가적인 기능을 만드는 일이 점포 업무 자체를 다루는 애플리케이션을 만드는 것보다 더 많은 공수가 들기도 한다. REST API 덕분에 개발자는 핵심 가치에 훨씬 더 집중할 수 있게 됐고 부가 기능을 만드는 데 드는 노력을 줄일 수 있었다. 초기에는 API 맞춤형 문서와 클라이언트 라이브러리를 만드는 일을 API 제공자가 담당했다. 하지만 스웨거와 OpenAPI가 REST API를 기술하는 공통언어로 확실하게 자리 잡게 되자, API 문서를 훨씬 빠르고 효율적으로 작성하고 사용할 수 있게 됐다.

이 책에서 조시와 루카스는 총체적인 접근 방식으로 API 설계와 구현을 가르친다. 흥미롭고 적절한 예제를 사용해 기존 API를 OpenAPI 문법에 맞는 문서로 작성하는 방법을 먼저 가르치고, 이를 확장해서 설계 우선 기법을 소개한다. OpenAPI를 쉽게 사용할 수 있게 해주는 멋진 도구와 오픈소스 소프트웨어가 없다면 OpenAPI는 지금처럼 널리 사용되지 못했을 것이다. 이 책은REST API를 설계하고 구현하고 공유하고 탐구하는 데 많은 도움을 주는 강력한 도구도 함께 다룬다.

애플리케이션이 점점 더 복잡해지고 최종 사용자는 지속적으로 안정적인 기능을 기대함에 따라 OpenAPI를 비롯한 명세 기반의 표준에 대한 의존도는 불가피하게 계속 높아질 것이다. 이 책은 API를 다루는 모든 소프트웨어 개발자 경험을 향상할 수 있는 다양한 패턴과 기법을 명확하게 제시한다.
- 토니 탐(Tony Tam) / 스웨거 창시자이자 애플 아이클라우드(iCloud) 혁신 리드

대부분의 소프트웨어 개발은 팀 협업의 결과물입니다. 물론 클라우드 등 인프라 서비스의 발달로 개발자들이 더더욱 핵심 로직 개발에 집중할 수 있는 환경이긴 합니다만, 예전이나 지금이나 이해하기 쉬운 코드와 문서화가 협업에 정말 중요하다는 사실은 변하지 않았다고 생각합니다. 사실 팀 협업뿐만 아니라 좋은 설계를 위해서도 코드를 문서화하는 방법은 매우 중요합니다. 설계/코딩을 하면서 혹은 그에 앞서 문서를 작성하고, 문서를 작성하는 과정에서 검토한 내용을 반영해서 다시 설계를 수정하기도 하니까요. 문서화는 소프트웨어 개발의 모든 라이프사이클의 마지막이 아닌 각 단계마다 포함되어야 하는 과정입니다.

그러므로 문서화를 개발 사이클에 녹여넣는 도구의 선택은 단순히 도구의 효율성 문제가 아니라 설계 과정이나 코딩 방식에 큰 영향을 미치는 선택입니다. 약 20년 전 제가 개발자로서의 경력을 막 시작한 즈음, 가장 큰 영향을 준 도구 역시 C 코드를 분석해서 API 문서를 생성해주는 doxygen이라는 문서화 도구였습니다. 문서와 설계 의도, 코드의 동작을 상시적으로 동기화시키는 것은 한번 겪게 되면 빠져나올 수 없는 경험이어서 팀내 도입을 진행한 바 있습니다. 그리고 각자 자기만의 주석 컨벤션을 가지고 있던 시절이다 보니 팀에서 주석 컨벤션을 일치시킬 수 있었던 것도 매우 큰 개선이었습니다. 

당시 팀에 문서화 도구를 도입하는 과정은 기존 관습을 깨는 작은 혁명 같은 것이었고 자료가 적다 보니 조금 고생을 하기도 했습니다. 최근 OpenAPI와 OpenAPI 생태계에 포함된 좋은 도구들을 보면서 지금 시점에 개발자 커리어를 시작하는 분들이 부러웠는데, OpenAPI의 사용법을 친절하게 설명해주는 책이 나왔다니 더욱 반가운 소식이 아닐 수 없습니다. 이 책에서는 1부에서 API 사용법을 설명한 다음에 특히 2부부터는 문서화 도구를 잘 활용한 소프트웨어 설계 방법을 적절한 사례를 들어가며 설명하는데, 이야말로 도구와 시대를 가리지 않는 지혜이므로 설계 과정의 문서화 도입에 조금이라도 고민하던 분이라면 꼭 이 책을 잘 참고해서 활용해보시길 바랍니다.
- 양석호 / 라인야후(LY Corporation) 데이터그룹 CTO

엔터프라이즈 개발을 수행하다 보면 고민이 되는 부분이 한두 가지가 아니지만, 깔끔한 해법이 없어서 가장 고민하던 부분이 바로 API 설계와 문서화, 테스트였다. 스타트업 백엔드 개발자이자 CTO로서 회사 프로젝트에 스프링 REST Docs를 써보기도 하고 직접 마크다운을 사용해 문서를 작성해봤지만, API 명세를 기술하고, 테스트 스텁이나 테스트 코드를 자동으로 생성하며, 만들어진 문서의 품질도 깔끔한, 만족스러운 해법을 찾기는 어려웠다. 그러던 중 몇 년 전 스웨거와 OpenAPI를 활용하면서 API 설계부터 구현, 테스트, 공개에 이르는 전 과정을 다른 해법들보다 훨씬 깔끔하게 수행할 수 있었고 결과물도 상당히 만족스러웠다. 

이 책은 단순히 스웨거 UI나 도구를 사용하는 방법을 설명하는 데 그치지 않고, API를 설계하고 구현하고 테스트하며 공유하는 각 단계를 스웨거와 OpenAPI를 통해 어떻게 좀 더 편리하게 수행할 수 있는지를 보여주면서 다양한 문제점을 해결하는 방법도 소개해주기 때문에, API는 물론이거니와 '애플리케이션 전반의 설계와 구현에 대한 안내서'라고도 할 수 있다. 무엇보다도, 늘 믿고 읽을 수 있는 명운님의 깔끔한 번역이 책의 내용을 더 명확하게 이해할 수 있게 해준다. 스웨거와 OpenAPI를 배우고 싶은 개발자분들뿐 아니라 도메인 모델과 API를 중심으로 애플리케이션을 설계하고 갱신해 나가는 과정을 살펴보고 배우고 싶은 분들에게도 이 책을 권하고 싶다.
- 오현석 / (주)모빌리티42 CTO, 기술 번역가

OpenAPI를 이렇게 잘 설명한 책은 여태 보지 못했다. 개발의 결과물이 API가 아닌 API의 결과물이 개발인 이유를 알려주는 책이다. HTTP 프로토콜 기반 API로 다양한 서비스 간 연결을 구성해 복잡하고 다양한 도메인을 만들어 가는 전반적인 과정과 방법을 조목조목 알려준다. API를 가지고 협업하거나 개발하는 방식이 표준이 있는 것도 아니라 환경과 팀의 스타일에 따라 제각각인 것이 현실이다. 그래서 다들 우리가 하고 있는 API 개발 방식과 협업하는 방식이 제대로 하고 있는 것인지 의문을 가지곤 하는데, 이 책은 코드 한 줄 없이 API를 정의하고 명세하고 문서화하는 방법을 제시하고 있다. 게다가 초기 협업부터 가독성 높게 API 명세를 문서화하는 방법과 협업을 통한 도메인 모델링을 다루는 다양한 방법 등, 실무에서 적용하거나 활용할 만한 내용으로 가득하다. 

‘API의 정의와 설계 그리고 검증을 잘 하고 싶다’, ‘가독성 높고 퀄리티 있는 API 문서화를 하고 싶다’, ‘API 기반으로 효율적인 협업을 하고 싶다’ 와 같은 현실을 마주하고 있다면 이 책은 해결 방법과 실마리를 제공해 줄 것이다. 
- 오창훈 / (주)토스증권 CTO 

모바일 앱 혹은 웹 서비스를 만드는 일은 간단하게 정리하면 1) 뭘 만들지 결정하고, 2) 열심히 개발한 뒤, 3) 사용하는데 문제가 없는지 테스트하고, 4) 배포하는 과정을 밟아가는 일입니다. 이 과정에서 1)과 2) 사이에 반드시 진행하는 일이 서버와 클라이언트 사이의 API를 결정하는 것입니다. 이제는 너무 자연스럽게 진행하는 작업이라 특별히 중요한 작업이라 생각하지 않는 경우가 많지만 실제로 이 API는 서버와 클라이언트 모두에게 큰 영향을 미칩니다.

API의 모습에 따라서 로직의 위치가 서버나 클라이언트 중 한 곳으로 정해지기도 합니다. 이에 따라 단 한 번의 클라이언트 요청으로 모든 작업을 처리할 수도 있고, 하나의 작업을 처리하게 위해 여러 번의 요청을 클라이언트에서 보내야 할 수도 있습니다. 결과적으로 서비스를 이용할 때 사용자가 체감하는 품질에까지 영향을 미칠 수도 있습니다. 어떨 때는 API에 따라 클라이언트의 작업이 많아질 수도 있고, 반대로 서버의 작업이 많아질 수도 있으니 API를 결정할 때 개발해야 할 분량이나 이후 운영할 때의 업무량을 고려하여 양쪽 사이에 신경전이 벌어지는 경우가 발생한다고 해도 이상하지 않을 것 같습니다(물론 제가 겪은 개발자들은 각자 전문성을 발휘하여 사용자에게 가장 좋은 선택을 하는 경우가 대부분이었습니다). 

여기서 끝이 아닙니다. 서비스를 시작하고 난 후에는 이런 API가 점점 쌓여가기 마련입니다. 기억을 떠올려 보면 서비스의 배포 횟수만큼 기능이 추가되고 그만큼 API가 늘어나는 것 같기도 합니다. 한번 만들고 나면 수정이 쉽지 않다는 것도 API를 만들 때 고려해야 할 점인데 종종 모바일 앱을 업데이트하지 않는 사용자가 있기 때문입니다. 서비스를 운영하는 입장에서는 어제까지도 잘 사용했던 서비스를 오늘 갑자기 사용하지 못하게 되는 경험을 피하고 싶기 때문에 서비스를 이용하는 데 문제가 될 수 있는 API의 수정은 가급적 피하고 새로운 API를 도입하는 경우가 많습니다. 이렇듯 점점 늘어나는 API가 개발자에게는 때때로 부담스럽기도 합니다.

이 책은 API를 사이에 두고 다른 개발자와 함께 일하는 분들이 꼭 읽어보면 좋겠습니다. OpenAPI 규격을 기반으로 API를 만드는 방법을 설명하는 이 책은 OpenAPI 이해와 API 설계라는 기술적인 면에 한정하지 않고, 서버와 클라이언트 개발자가 함께 API를 만들고 활용하는 방법까지 안내합니다. 이 책을 통해 OpenAPI를 처음 접한다면 OpenAPI 규격을 지원하는 다양한 도구를 활용해 업무를 편리하게 수행할 수 있다는 점은 추가로 얻게 되는 장점이라고 하겠습니다. 이 책을 읽으시는 모든 개발자가 더 좋은 API를 만들 수 있기를 바랍니다. 그리고 API를 활용하는 많은 개발자가 즐거운 마음으로 개발하고, 사용자들은 멋진 서비스를 이용하게 되면 좋겠습니다. 덕분에 저도 훌륭한 서비스를 이용할 수 있기를 기대합니다. :) 
- 장정환 / 카카오 FE플랫폼팀 기술이사

지은이 조시 포널랫Josh Ponelat

스마트베어(SmartBear)의 스웨거 오픈소스를 담당하고 있다. API 관련 마찰을 최소화하고 팀이 더 나은 도구를 만들도록 돕는 것을 목표로 한다. 조시는 지구의 남쪽 끝에 있는 남아프리카 공화국에 거주하는 커피 애호가이며 말장난을 즐긴다. 어디에서든 ‘ponelat’이라는 계정을 사용하며, 아마추어 지도 제작, 소형 제품 제작, 고급 노트 필기법에 관심이 있다면 주저하지 말고 슬랙이나 그 밖의 온라인 포럼에서 조시를 찾아보자.

지은이 루카스 로젠스톡Lukas Rosenstock

스타트업과 대규모 조직을 대상으로 API 라이프사이클 관련 컨설팅, 개발, 기술 문서 작성을 지원하는 프리랜서 기업가다. 유럽의 중심부인 독일에 살고 있으며, 맥주를 좋아하지 않는 이상한 독일인이자 커피를 마시지 않는 이상한 엔지니어다. 맥주와 커피 대신에 차를 즐겨 마신다. API 관련 일이나 코딩으로 바쁘지 않을 때는 밤 늦게까지 보드 게임을 즐기고 효과적인 이타주의로 더 나은 세상을 만드는 방법을 고민한다. 트위터(@LukasRosenstock)에서 루카스를 만날 수 있다.

REST API 문서 정의와 작성을 도와주는 도구 모음인 스웨거를 사용하면 보안이 적용된 굉장히 쓸모 있는 API 설명 문서를 제공할 수 있다. 스웨거는 특정 회사에 종속적이지 않은 표준인 OpenAPI 명세를 구현하므로, 스웨거를 사용하면 구글이나 마이크로소프트, 아마존에서 수용한 것과 동일한 표준을 사용하게 된다.

이 책에서는 설계 우선 접근방식(design-first approach)을 소개한다. API 설계를 처음 접하는 개발자는 개념 정립부터 제품 수준에 이르기까지 API의 전체 생애주기를 익힐 수 있다. 점진적으로 예제를 완성해가면서 API 설계와 개발에서 해야 할 일과 하지 말아야 할 일을 배워본다. 문서와 개발자 친화적인 목(mock)이나 클라이언트 SDK를 자동으로 생성해주는 도구를 사용해서 비즈니스 요구사항에 맞는 API를 설계하는 실무 경험을 쌓을 수 있다. 스웨거나 OpenAPI에 대한 아무런 사전 지식이 없더라도 웹 개발자라면 충분히 읽을 수 있다.

옮긴이 오명운 

번역을 통해 개발자 생태계에 조금이라도 보탬이 되고자 인공지능과 무모한 경쟁을 벌이고 있는 인간지능 번역자. 『실전 스프링 부트』(제이펍, 2023), 『스프링 부트 실전 활용 마스터』(책만, 2021), 『엔터프라이즈 데이터 플랫폼 구축』(책만, 2020) 등을 번역했으며, 적은 양이라도 꾸준히 번역 작업을 이어갈 생각이다. https://github.com/HomoEfficio/dev-tips에 잡다한 문제 해결 기록을 남기고 있으며, 현재 네이버제트에서 글로벌 메타버스 서비스 제페토(Zepeto)를 만들고 있다.

인터넷이 세상에 나온 지 그리 오래되지 않았을 때, 집 밖에 나가지 않고 인터넷만으로 얼마나 잘 지낼 수 있는지를 실험해보는 체험 예능 컨텐츠가 있었던 걸로 기억합니다. 하지만 이제 그런 예능은 아무도 보지 않을 것 같습니다. 스마트폰을 사용할 수 있다면 누구든 인터넷만으로 불편 없는 삶을 영위할 수 있다는 사실을 누구나 알고 있으니까요. 이처럼 손 안에서 몇 번의 스와이프와 클릭만으로 물건을 받아 사용할 수 있고 음식을 배달받아 먹으며, SNS를 통해 이 모든 것을 자랑까지 할 수 있게 된 편리한 세상을 돋보기로 계속 확대하면서 들여다보면 그 마디마디에 API가 숨어 있음을 확인할 수 있을 것입니다. API는 다양한 소프트웨어의 연결점 역할을 하면서 이 세상을 든든하게 떠받치고 있습니다.

소프트웨어의 연결점 역할을 하는 API는 소프트웨어 개발자들에게는 의사소통 수단으로 사용됩니다. 원활한 의사소통을 위해서는 주고받는 데이터 형식과 호출 방식을 정의하는 규격과 그에 대한 친절한 설명을 작성해야 합니다. 즉 API를 기술해야(describe) 합니다. OpenAPI는 HTTP 프로토콜 기반의 HTTP API를 기술하는 표준 명세이며, 표준이 있으면 자동화가 가능해지므로 OpenAPI를 통해 많은 작업을 자동화할 수 있습니다.

이 책은 OpenAPI를 사용해서 API 정의서를 기술하는 방법을 설명합니다. 그걸로 그쳤다면 그다지 재미없는 책이 될 수도 있었을 텐데, 작은 웹 서비스의 요구 사항을 정리하고, 사용자 스토리를 작성하고, 이를 바탕으로 비즈니스 도메인 모델을 설계하고, 이를 반영한 API를 설계하고, OpenAPI를 사용해서 API 정의서를 작성하고, 정의서를 바탕으로 자동화를 이용해 개발 생산성을 높이고, 시간이 지남에 따라 API를 매끄럽게 진화시켜 확장하는 방법까지 그야말로 모든 것을 다루고 있습니다.

API를 설계하고는 있지만 어쩌면 별다른 학습이나 기준 없이 편의성만을 생각하며 설계하고 구현하다가 나중에 확장하기 어렵게 되는 안타까운 일이 실무적으로 많이 발생하는데, 이 책에 나오는 모범 사례를 읽다 보면 자연스럽게 확장성 있는 API를 설계하는 데 필요한 지식을 얻을 수 있습니다. 이런 내용만으로도 유익할 텐데, 이 모든 과정을 지루하고 딱딱한 설명이 아니라 실제로 작은 프로젝트 팀이 구성되고 각자의 역할을 수행하며 난관에 부딪치고 해결하는 모습을 묘사하는 형식으로 전개하고 있어 흥미진진하고 재미있기까지 합니다. 게다가 예제를 위해 간혹 특정 기술을 사용하고 있기는 하지만 본질적으로 특정 도구에 종속되는 내용이 아니라서, 한마디로 API를 만들고 활용하는 개발자 모두에게 재미있고 유익한 책입니다.

이 책의 내용이 전반적으로 OpenAPI를 사용해 새로운 시스템을 설계하고 만들어 가는 과정을 보여주고 있어서 이미 만들어진 시스템에는 적용할 수 없는 건가라는 의문이 들 수도 있는데, 다행스럽게도 기존 시스템에도 적용할 방법이 있습니다. 국내에서 API 서버 개발에 가장 널리 사용되는 스프링 부트 기반의 API 서버라면 아주 간단한 설정과 애너테이션만으로도 스웨거 UI 사이트를 자동으로 만들 수 있습니다. 단순한 예제지만 실무적으로 꽤 큰 도움이 될 것이라 생각해서 한국어판 특별부록으로 추가했습니다.

코딩도 그렇지만 번역도 늘 볼 때마다 개선점이 눈에 보입니다. 아마 원서를 작성한 저자들도 마찬가지일 겁니다. 번역자는 일차적으로는 원서를 우리글로 옮기는 일을 하는 사람이지만, 훌륭한 번역자는 먼저 독자의 입장에서 원서를 읽고 불편했던 점을 찾아 개선하고 최종 독자에게는 더 나은 결과물을 보여주는 사람이라고 생각합니다. 이번에도 모자람이 있겠지만 훌륭한 번역자 흉내라도 내보고 싶어서 원서보다 나은 역서를 목표로 번역 작업을 했습니다. 모쪼록 독자분들이 읽어나가시면서 마치 애초부터 한글로 쓰여진 책인 것처럼 술술 읽으실 수 있기를 욕심내어 바라봅니다.

차례

[1부] OpenAPI 형식으로 기존 제품의 API 기술해 보기
1장 API와 OpenAPI 소개 
__1.1 API 생태계란?
__1.2 API 기술하기
____1.2.1 브리짓의 업무
____1.2.2 브리짓 해법의 잠재력
__1.3 OpenAPI란?
____1.3.1 OpenAPI 정의서 예제
__1.4 OpenAPI 정의서는 어디에 사용하는 것이 좋을까?
__1.5 스웨거란?
__1.6 REST란?
__1.7 OpenAPI는 언제 사용하는가?
____1.7.1 API 사용자
____1.7.2 API 제공자
____1.7.3 API 설계자
__1.8 이 책의 구성
__1.9 정리

2장 API 요청 준비 
__2.1 문제 정의
____2.1.1 직판장 API 개요
____2.1.2 직판장 API의 처음 두 가지 작업
__2.2 포스트맨 준비
__2.3 직판장 API
__2.4 후기 목록 조회
____2.4.1 GET 요청 구성
____2.4.2 확인
__2.5 후기 남기기
____2.5.1 POST 요청 구성
____2.5.2 확인
__2.6 연습
____2.6.1 고양이에 관한 진실 API
____2.6.2 미니멀 아바타 API
____2.6.3 덕덕고 검색 엔진 API
____2.6.4 해적 은어 API
__2.7 용사를 위한 HTTP
__2.8 정리

3장 OpenAPI 정의서 첫인상 
__3.1 문제 정의
__3.2 OpenAPI 명세 소개
__3.3 YAML 훑어보기
___3.3.1 JSON에서 YAML로
__3.4 GET 연산 기술하기
__3.5 GET 연산 확장
__3.6 정리

4장 스웨거 에디터로 OpenAPI 정의서 작성 
__4.1 스웨거 에디터 소개
___4.1.1 에디터 패널
___4.1.2 UI 문서 패널
___4.1.3 도구 메뉴
___4.1.4 저장
__4.2 스웨거 에디터에서 OpenAPI 정의서 작성
___4.2.1 유효한 미니 OpenAPI 정의서
___4.2.2 스웨거 에디터에서 OpenAPI 정의서 작성
___4.2.3 검증
__4.3 GET /reviews 추가
__4.4 API 호출
___4.4.1 GET /reviews 호출
___4.4.2 OpenAPI 정의서에 서버 정보 추가
___4.4.3 GET /reviews 다시 호출
__4.5 정리

5장 API 응답 기술하기 
__5.1 HTTP 응답
__5.2 문제 정의
__5.3 놀라운 데이터 스키마의 세계
__5.4 JSON 스키마
___5.4.1 type 필드
___5.4.2 객체에 필드 추가
___5.4.3 minimum과 maximum
___5.4.4 number와 integer
__5.5 상태 코드
__5.6 미디어 타입(MIME)
__5.7 GET /reviews 응답 기술하기
___5.7.1 초미니 응답
___5.7.2 GET /reviews 200 응답 본문
___5.7.3 응답 본문에 rating 필드 추가
___5.7.4 message, uuid, userId 필드 추가
__5.8 정리

6장 자원 생성
__6.1 문제 정의
__6.2 POST /reviews와 요청 본문 기술하기
___6.2.1 요청 본문
___6.2.2 requestBody의 스키마
__6.3 새 후기 생성
___6.3.1 예시 추가로 try-it-out 기능 개선
__6.4 경로 파라미터를 포함한 GET /reviews/{reviewId} 기술하기
___6.4.1 경로 파라미터
___6.4.2 reviewId 경로 파라미터 기술하기
__6.5 후기 생성 확인
__6.6 정리

7장 인증과 인가 
__7.1 문제 정의
__7.2 인증 준비
___7.2.1 도전 과제: POST /users 기술하기
___7.2.2 도전 과제: POST /tokens 기술하기
___7.2.3 해법: 정의서 내용 변경
___7.2.4 사용자 및 토큰 생성 기능 확인
__7.3 Authorization 헤더 추가
___7.3.1 OpenAPI의 인가 처리 방식
___7.3.2 OpenAPI 3.0.x에서 지원하는 인가(보안) 방식
___7.3.3 보안 스킴에 Authorization 헤더 추가
___7.3.4 POST /reviews에 보안 요구사항 추가
___7.3.5 보안 기능 동작 확인
__7.4 선택적으로 보안 적용
__7.5 다른 방식의 보안 스킴
__7.6 보안 스킴을 적용하는 일반적인 방법
__7.7 정리

8장 API 문서 준비와 호스팅 
__8.1 문제 정의
__8.2 API 정의서에 메타데이터 추가
__8.3 마크다운으로 설명 작성
___8.3.1 마크다운 기초
___8.3.2 직판장 API 정의서에 마크다운 설명 추가
__8.4 태그로 연산 그룹 짓기
___8.4.1 GET /reviews 연산에 태그 추가
___8.4.2 태그에 설명 추가
___8.4.3 나머지 연산에 태그 추가
__8.5 Netlify.com과 스웨거 UI로 API 문서 호스팅
___8.5.1 OpenAPI 정의서로 스웨거 UI 준비
___8.5.2 Netlify.com에서 호스팅
__8.6 1부 마무리
__8.7 정리

[2부] OpenAPI와 스웨거를 활용한 API 설계 우선 방식 
9장 웹 애플리케이션 설계 
__9.1 펫시터 아이디어
__9.2 펫시터 프로젝트 착수
___9.2.1 추가 요구사항
___9.2.2 팀 구조
___9.2.3 API 중심 아키텍처
___9.2.4 계획
__9.3 도메인 모델링과 API
___9.3.1 API에 사용할 도메인 모델링
___9.3.2 직판장 API 돌아보기
__9.4 펫시터 도메인 모델
___9.4.1 모델에 사용되는 개념
___9.4.2 사용자 모델
___9.4.3 구인 공고와 반려견 모델
__9.5 펫시터 사용자 스토리
___9.5.1 사용자 스토리란 무엇인가?
___9.5.2 사용자 스토리 수집
___9.5.3 사용자 스토리 매핑
__9.6 정리

10장 OpenAPI를 사용한 API 설계 
__10.1 문제
___10.1.1 도메인 모델을 OpenAPI로 전환
___10.1.2 재사용성 보장
__10.2 스키마 생성
___10.2.1 스키마를 포함하는 OpenAPI 파일
___10.2.2 공통 스키마 참조
___10.2.3 User 스키마
___10.2.4 Job 스키마
___10.2.5 Dog 스키마
___10.2.6 JobApplication 스키마
__10.3 API 연산과 CRUD
___10.3.1 API 요청과 응답 정의
___10.3.2 사용자 스토리와 CRUD 설계
__10.4 펫시터 API
___10.4.1 User 스키마에 필요한 연산
___10.4.2 Job 스키마에 필요한 연산
___10.4.3 JobApplication 스키마에 필요한 연산
__10.5 정리

11장 API 설계 우선 방식에 변경 워크플로 구축 
__11.1 문제
__11.2 변경 논의와 대응
__11.3 워크플로 엔진으로서의 깃허브
___11.3.1 단일 진실 출처
___11.3.2 변경 제안
___11.3.3 변경 수용
___11.3.4 변경 비교 확인
__11.4 깃허브 워크플로 통합
___11.4.1 깃허브와 진실의 출처 구성
___11.4.2 깃허브 워크플로 단계
__11.5 워크플로 실무
___11.5.1 DELETE /jobs/{id} 추가 제안
___11.5.2 변경 검토 및 수용
___11.5.3 오래된 브랜치와 최신 브랜치 비교
___11.5.4 11장에서 수행한 내용
__11.6 정리

12장 프론트엔드 코드 구현과 변경 대응 
__12.1 문제
__12.2 프리즘 목 서버 구성
___12.2.1 프리즘 설치
___12.2.2 프리즘 동작 확인
__12.3 목 서버를 바탕으로 프론트엔드 개발
___12.3.1 OpenAPI 정의서에 예제 추가
___12.3.2 프리즘에 examples 적용
__12.4 누락된 API 연산 식별
___12.4.1 새 연산 추가 검토
___12.4.2 새 연산 설계
___12.4.3 프리즘으로부터 반환받을 목 데이터 선정
___12.4.4 변경 제안
___12.4.5 curl 예제
__12.5 정리

13장 Node.js와 스웨거 코드젠으로 백엔드 구축 
__13.1 문제
__13.2 스웨거 코드젠 소개
___13.2.1 클라이언트 코드 생성
___13.2.2 서버 코드 생성
___13.2.3 스웨거 제너레이터
__13.3 백엔드 구조
___13.3.1 백엔드 코드 생성
___13.3.2 백엔드 구조 분석
___13.3.3 OpenAPI 수정 내용
__13.4 백엔드 OpenAPI 수정
___13.4.1 operation ID 추가
___13.4.2 API 연산에 태그 지정
___13.4.3 백엔드 스텁 재생성
__13.5 백엔드 코드 실행과 테스트
___13.5.1 포스트맨으로 테스트
___13.5.2 입력값 검증 테스트
___13.5.3 프리즘으로 결괏값 검증
__13.6 몽구스로 데이터베이스 저장
___13.6.1 API 수정
___13.6.2 몽고디비 사용 준비
___13.6.3 몽구스 설정
___13.6.4 모델 생성
__13.7 API 메소드 구현
__13.8 정리

14장 웹 애플리케이션 통합 및 출시 
__14.1 문제
___14.1.1 인증
___14.1.2 코드 조직
___14.1.3 백엔드와 프론트엔드 컴포넌트를 함께 제공
__14.2 인가 구현
___14.2.1 보안 스킴 생성
___14.2.2 ‘Login’ 행위 추가
___14.2.3 연산 보안 정의
__14.3 리포지터리 관리
___14.3.1 기존 구조 유지
___14.3.2 공유 깃 리포지터리 사용
___14.3.3 코드와 API 정의서를 하나의 리포지터리에 통합
___14.3.4 결정 및 리팩터링
__14.4 통합 웹 서버 구성
___14.4.1 URL 설계
___14.4.2 서버 구성
__14.5 정리

[3부] 제품 출시 이후 API 확장과 진화 
15장 2차 API 설계 
__15.1 첫 번째 개발 스프린트 검토
__15.2 다음 스프린트 계획
__15.3 새 기능 준비
___15.3.1 도메인 모델 재검토
___15.3.2 사용자 스토리 검토
__15.4 개발자 경험 개선
___15.4.1 일관성
___15.4.2 에러 처리
___15.4.3 입력값 유효성 검증
___15.4.4 버전 관리와 진화
__15.5 정리

16장 OpenAPI 합성을 사용한 스키마 설계 
__16.1 문제
__16.2 도메인 모델 다형성과 상속
__16.3 스키마 업데이트
___16.3.1 Pet 스키마
___16.3.2 Dog 스키마
___16.3.3 Cat 스키마
__16.4 OpenAPI의 다형성과 상속
___16.4.1 Dog 스키마와 Cat 스키마 안에서 합성
___16.4.2 Pet 스키마 안에서 합성
__16.5 OpenAPI 구분자 추가
__16.6 정리

17장 컬렉션 엔드포인트에 필터와 페이징 적용 
__17.1 문제
__17.2 필터링 설계
___17.2.1 프로젝션 필터
___17.2.2 셀렉션 필터
___17.2.3 중첩 스키마 처리
___17.2.4 쿼리 언어
___17.2.5 특수 관례
__17.3 펫시터 필터링
___17.3.1 필터링 기준 필드 선정
___17.3.2 OpenAPI에 필터링 적용
___17.3.3 필터 포함 요청
__17.4 페이징 설계
___17.4.1 오프셋 기반, 페이지 기반 페이징
___17.4.2 커서 기반 페이징
__17.5 펫시터에 페이징 적용
___17.5.1 OpenAPI에 페이징 적용
___17.5.2 요청 예제 확장
__17.6 정렬 설계
___17.6.1 단일 필드 정렬
___17.6.2 다중 필드 정렬
___17.6.3 파라미터 타입 일관성
__17.7 펫시터에 정렬 적용
___17.7.1 정렬 필드
___17.7.2 정렬 파라미터 설계
___17.7.3 OpenAPI 정의서에 정렬 기능 추가
___17.7.4 필터링, 페이징, 정렬이 모두 적용된 요청 예제
__17.8 정리

18장 problem+json을 활용한 예외 처리 
__18.1 문제 정의
__18.2 에러 분류
___18.2.1 실패 상황 찾기
___18.2.2 공통 에러 패턴
__18.3 에러 응답 요구사항
__18.4 OAS 도구 형식
__18.5 problem+json 형식
__18.6 OpenAPI 정의서에 에러 응답 추가
___18.6.1 에러 스키마 생성
___18.6.2 연산에 에러 응답 추가
__18.7 에러 처리 가이드
___18.7.1 프론트엔드 개발
___18.7.2 백엔드 개발
__18.8 정리

19장 고급 JSON 스키마를 활용한 입력값 유효성 검증 
__19.1 문제 정의
__19.2 유효성 검증 세부 기능
___19.2.1 readOnly, writeOnly 프로퍼티
___19.2.2 숫자 제약사항 강제
___19.2.3 문자열 형식 강제
___19.2.4 배열 제약사항 강제
___19.2.5 열거형 정의
___19.2.6 필수 프로퍼티와 선택 프로퍼티 목록
___19.2.7 기본값 지정
__19.3 펫시터 스키마 업데이트
___19.3.1 User 스키마
___19.3.2 Job 스키마
___19.3.3 JobApplication 스키마
___19.3.4 Pet, Dog, Cat 스키마
__19.4 정리

20장 API 버전 관리와 중대 변경 처리 
__20.1 문제 정의
__20.2 중대 변경이란?
__20.3 중대 변경 출시
___20.3.1 중대 변경 조율
___20.3.2 API 버전 관리
___20.3.3 미디어 타입을 활용한 스키마 버전 구분
___20.3.4 기능 추가/삭제 예고
__20.4 정리

21장 API 출시 전 체크리스트 
__21.1 공개 API의 장점과 단점
__21.2 체크리스트
__21.3 API 정상 동작
___21.3.1 API 단위 테스트
___21.3.2 종단 간 테스트
__21.4 문서화
__21.5 API 일관성 확보
__21.6 유효성 검증과 에러 보고
__21.7 API 로드맵과 인덱스 공개
__21.8 변경 전략
__21.9 보안 개선
__21.10 API 모니터링
___21.10.1 지표 수집 구성
__21.11 API 출시
___21.12 정리

부록 A 스웨거 2.0, OpenAPI 3.0, OpenAPI 3.1
부록 B [한국어판 특별부록] 스프링 부트 웹서비스에 스웨거를 입혀 활용하는 방법