OpenAPI와 스웨거를 활용한 실전 API 설계 조시 포널랫(Josh Ponelat) pdf 다운로드를 무료로 제공합니다 스마트한 개발을 원하는 백엔드 개발자는 물론, 프로젝트 테크니컬 PM과 PO, 프론트엔드 개발자가 모두 함께 읽어야 할 필독서!
관련 교재 pdf 모음
책 소개
이 책은 API를 기술하고(describe) 설계하는(design) 방법을 다룬다. OpenAPI 세상으로 인도하는 입문서로서, 설계 우선 원칙을 실천하는 API 개발자가 사용하는 도구와 사례를 들여다본다.OpenAPI 정의서를 읽고 쓰는 기초부터 시작해서 도메인 설계, 워크플로 변경, API 디자인 패턴으로 나아간다. OpenAPI와 API 설계에 초점을 맞추지만 API 라이프사이클 전반에 걸친 주제를 모두 다루려고 노력했으며 기술 관점과 프로젝트 관리 관점을 두루 살펴볼 수 있다. OpenAPI가 어떤 문제를 해결해 주는지, 왜 존재하는지, 어떻게 사용하는지 이해하고 자신감을 갖는 데 이 책이 도움이 되었으면 한다. API에 흥미를 갖고 설계 우선 방식으로 API를 활용해 보려는 소프트웨어 개발자가 읽어야 하는 책이다. 프론트엔드 또는 백엔드 개발자, 제품 관리자, QA 테스터, 심지어 CEO까지 API 관련 의사결정을 내려야 하는 모두가 읽어야 한다. 특정 주제를 심도 깊이 이해하고 있지 않더라도 책을 읽을 수 있도록 주의를 기울였으며, JSON이나 HTTP 같은 개념에 익숙하다면 책을 읽는 데 아무런 문제가 없을 것이다. 또한 간단한 복습과 외부 자료에 대한 링크도 많이 담았다.
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 [한국어판 특별부록] 스프링 부트 웹서비스에 스웨거를 입혀 활용하는 방법