16-1. Spring REST Docs - 실제 사용해보기

사전 세팅 및 개념 정리

# 먼저 Spring initializr 에서 기본 세팅을 한 후 프로젝트를 생성한다.

• Spring Web : API 를 만들기 위해 설정
• Spring Data JPA : 데이터베이스에서 CRUD 를 하기 위한 설정 (ORM 도구)
• Validation : Bean 의 유효성 검사를 위한 설정
• Spring REST Docs 
• Lombok : 로그를 좀 더 편하게 보기 위한 설정
• MySQL Driver : MySQL 를 연동하기 위한 설정

# 문서화를 위한 API

• 생성 : POST /api/user
• 조회 : GET /api/user/{id}
• 수정 : PUT /api/user
• 삭제 : DELETE /api/user/{id}

# 실습 순서

1. 프로젝트 생성
2. 실습에 필요한 테스트 API 코드 작성
3. Spring REST Docs 관련 설정 추가
4. Test Code 작성으로 스니펫 (Snippets) 생성
5. 스니펫에 의해 HTML 문서가 만들어지도록 adoc 파일 구성
6. 빌드 시 생성된 HTML 파일이 호스팅되도록 설정

# Spring REST Docs + Swagger 를 조합하여 사용

1. Spring REST Docs 로 만들어지는 문서 설정을 기반으로 OpenAPI Spec 파일을 생성
2. 오픈 소스
   • Gradle : https://github.com/ePages-de/restdocs-api-spec
   • Maven : https://github.com/BerkleyTechnologyServices/restdocs-spec
3. Swagger UI 를 띄우고 생성된 OpenAPI Spec 파일을 읽는 방식
4. Spring REST Docs 의 장점
   • TEST 를 통과해야 문서가 생성
   • Product 코드에 영향 없음
5. Swagger 의 장점
   • API 테스트 UI 를 제공
6. MSA 환경 등 여러 API 문서를 한 곳에서 조회 가능

 

※ OpenAPI Spec
: REST API 에 대한 설명, 생성, 사용 및 시각화하기 위한 인터페이스 파일의 사양
: Swagger 프레임워크의 일부였지만 오픈소스로 전환
: 기본 내용
  - endpoint
  - HTTP Method, parameters
  - Input / Output
  - Authentication methods
  - Contact information, license, terms of use and other information
: YAML 또는 JSON 으로 작성 가능


※ MSA (MicroService Architecture)
: 마이크로 서비스란 작고, 독립적으로 배포 가능한 각각의 기능을 수행하는 서비스로 구성된 프레임워크
마이크로 서비스는 완전히 독립적으로 배포가 가능하고, 다른 기술 스택 (개발 언어, 데이터베이스 등)이 사용 가능한 단일 사업 영역에 초점을 둔다.

출처 : https://wooaoe.tistory.com/57

 

# 데이터베이스 생성하여 user 테이블에 데이터 하나 주입해놓기

 

# @PostMapping, @GetMapping, @PutMapping, @DeleteMapping 을 이용해서 기본 RESTful API 구현해놓기

http://localhost:8080/api/user/1