스마트한 개발을 원하는 백엔드 개발자는 물론, 프로젝트 테크니컬 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 정의서를 생성한다 - 프로세스를 자동화하고 코드를 자동 생성해 본다 - 기능 조직 간 협업 방식을 배운다

[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 [한국어판 특별부록] 스프링 부트 웹서비스에 스웨거를 입혀 활용하는 방법