Spring Boot 활용 REST API 설계 및 문서화

지니🧸·2023년 9월 9일

API문서화 api설계 스프링부트

Spring & Spring Boot

목록 보기

37/42

백엔드에 관하여

백엔드 직무

요구사항 분석
API 스펙 정의
인프라 구축, 설계 및 운영
데이터베이스 구축, 설계 및 운영
백엔드 코드 구현
보안 체계 도입
내부 스크립트 도구 제작

개발 프로세스

소프트웨어 개발 프로세스: 소프트웨어 제품을 개발하기 위해 필요한 과정

요구사항 분석: 수집 및 분석
API 스펙 개발: 스펙을 정의하여 프론트엔드에 공유 및 개발
테스트 & QA: 요구사항과 비교하여 테스트 및 QA
배포: 각 환경별로 버전 배포

REST API

API (Application Programmig Interface)

서버와 데이터베이스의 출입구
- 중요한 정보가 저장되는 데이터베이스에 대한 접속 통제 필요
- API가 허용된 사람들에게만 접근성 부여
프로그램 간 통신
- 어플이나 프로그램 등의 통신 매개체 역할 수행
- API가 어플리케이션과 기기가 데이터를 원활히 주고받을 수 있도록 도움
모든 접속을 표준화
- 기계/운영체제 등과 상관없이 누구ㅏ 동일한 접근 가능
- API가 범용 플러그와 같은 역할을 수행한다

REST

REST (Representational State Transfer)

목적: 웹(HTTP) 설계의 장점을 최대 활용할 수 있는 아키텍쳐
구성
- 자원(Resource): URI
- 행위(Verb): HTTP METHOD
- 표현(Representations)

특징
- Uniform interface
  - URI로 지정한 리소스에 대한 조작을 통일함
  - 한정적인 인터페이스로 수행함
- Stateless (무상태성)
  - 작업을 위한 상태정보를 따로 저장/관리하지 않음
    - 세선/쿠키 정보 저장 안함
  - API서버는 들어오는 요청만 처리하면 됨
  - 서비스의 자유도 증가
  - 단순한 구현
- Cacheable (캐시 가능)
  - HTTP 웹표준을 그대로 사용하기 때문에 웹에서 사용하는 기존 인프라를 그대로 활용할 수 있다
- Self-descriptiveness
  - REST API메시지만으로도 쉽게 이해할 수 있다
  - 자체 표현 구조
- Client-server 구조
  - REST 서버: API 제공
  - 클라이언트: 사용자 인증, 컨텍스트(세션, 로그인 정보) 등을 직접 관리
  - 각각의 역할이 잘 구분되어 서로간 의존성 감소
- 계층형 구조
  - REST 서버는 다중 계층으로 구성되어 있음
  - 보안, 로드 밸런싱, 암호화 계층 추가 가능
  - 구조상의 유연성
  - PROXY, 게이트 등 네트워크 기반 중간매체 도입 가능

Spring Framework

Spring Boot: 스프링의 문제점을 해결하기 위해 개발된 스프링의 프레임워크

Inversion of control (제어 역전)
- 스프링은 객체의 생명 주기 및 의존성 관리를 담당하는 IoC 컨테이너를 제공한다
- 개발자는 객체의 생성과 관계 설정을 스프링에 위임할 수 있고,
- 스프링 컨테이너가 객체의 생명 주기를 관리하고 필요한 의존성을 주입한다
Dependency injection (의존성 주입)
- 스프링은 의존성 주입을 통해 객체 간의 관계를 설정한다
- 의존성 주입은
  - 애플리케이션의 결합도를 낮춤
  - 유연성과 테스트 용이성 향상
AOP 지원: 관점 지향 프로그래밍
- 스프링은 AOP를 지원한다
- 애플리케이션의 핵심 비지니스 로직과 부가적인 기능 (로깅, 트랜잭션 관리 등)을 분리 및 모듈화 가능
웹개발 지원
- 웹 애플리케이션 개발을 위한 다양한 기능과 웹 프레젠테이션 계층을 제공한다
스프링 MVC (Model-View-Controller 아키텍쳐)
- 유연하다
- 확장 가능하다

MVC

Model

데이터와 애플리케이션이 무엇을 할 것인지 정의한다
내부 비즈니스 로직을 처리한다
Controller가 Model을 호출하면 Model이 데이터베이스와 연동하여 사용자의 입출력 데이터를 다룬다
역할: 데이터 추출, 저장, 삭제, 업데이트 등

View

사용자에게 보여주는 화면 >> UI
사용자와 상호작용하며 Controller부터 받은 모델의 결과값을 사용자에게 화면으로 출력한다
Model에서 받은 데이터를 저장하지는 않는다
여러 개의 View가 존재할 수 있다

Controller

Model과 View 사이를 이어주는 인터페이스
Model이 데이터를 어떻게 처리할지 알려준다
사용자가 View에 요청하면 Controller는 해당 업무를 수행하는 Model을 호출하고, Model이 업무를 모두 수행하면 다시 결과를 View에 전달하는 역할을 한다

Spring Boot Component

Controller

@RestController
@RequestMapping("/api")
public class SampleRestController {
	@GetMapping("/hello")
    public String sayHello() {
    	return "Hello, World!";
    }
}

@Controller vs. @RestController

	@ Controller	@Rest Controller
의미	Spring MVC controller	special controller used in RESTful Web services; @Controller + @ResponseBody
관계	@Component의 종류	@Controller의 종류
용도	클래스가 컨트롤러임을 선언	클래스가 컨트롤러이고, 클래스 내의 @RequestMapping 메서드는 @ResponseBody를 상정한다
활용	각 핸들러 메서드마다 @ResponseBody 명시해야 함	그럴 필요 없음
View	View를 리턴할 수 있다	View를 리턴할 수 없다

Service

Repository에서 얻은 정보를 바탕으로 가공한 후에 다시 Controller에게 정보를 보낸다
실질적으로 중요한 작업처리가 일어나는 곳
애플리케이션의 비즈니스 로직 처리와 비즈니스 관련 도메인 모델의 적합성 검증 및 트랜잭션 처리

@Service
public class SampleService {
	public String generateGreeting(String name) {
    	return "Hello, " + name + "!";
    }
}

Repository

@Repository

데이터베이스에 접근하는 클래스임을 명시한다
스프링 데이터 접근 계층으로 인식하고 데이터 계층의 예외를 스프링 예외로 변환해준다
JPARepository

@Repository public interface UserRepository extends JpaRepository<User, Long> {
	User findByUsername(String username);
}

프로젝트 환경 구성

프로젝트 구성: Java 17, Spring Boot, JPA, MySQL, Freemarker, Gradle, AWS

REST API 문서 설계

Open API: specification
Swagger: tools for implementing the specification

OpenAPI 3

API를 설명하고 문서화하기 위한 오픈소스 포맷
RESTful API를 설계/설명하기 위한 사실상의 표준

Swagger

REST API를 설계, 빌드, 문서화 및 사용하는데 도움이 되는 오픈 소수 도구 세트
annotation을 통해 문서를 작성할 수 있다

API 설계 실습

전체 사용자를 조회하는 API URI 를 정의해보시오.

GET /users

특정 사용자의 인적 사항(profile)중 이름(name)으로 조회하는 API URI 를 정의해보시오.

GET /users/profile?name=John&locale=en
or
GET /users/profile?q=name:John+locale=en

name 으로 query parameter 를 고정하게 되면 항목마다 처리하게 되므로 general 하게 q 라는
파라미터를 이용하여 그 안에 들어간 내용을 파싱하여 사용하는 형태로도 구현을 할 수 있습니다.

특정 사용자의 인적 사항(profile)을 삭제하는 API URI 를 정의해보시오.

DELETE /users/{userId}/profile

참고:

YC Tech Academy 강의교안 1장 자료
https://www.geeksforgeeks.org/difference-between-controller-and-restcontroller-annotation-in-spring/

지니🧸

우당탕탕

다음 포스트

Spring Boot 활용 REST API 설계 및 문서화

Spring & Spring Boot

백엔드에 관하여

백엔드 직무

개발 프로세스

REST API

REST

Spring Framework

MVC

Model

View

Controller

Spring Boot Component

Controller

@Controller vs. @RestController

Service

Repository

프로젝트 환경 구성

REST API 문서 설계

OpenAPI 3

Swagger

API 설계 실습

전체 사용자를 조회하는 API URI 를 정의해보시오.

특정 사용자의 인적 사항(profile)중 이름(name)으로 조회하는 API URI 를 정의해보시오.

특정 사용자의 인적 사항(profile)을 삭제하는 API URI 를 정의해보시오.

4. Spring Security

0개의 댓글