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

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