Spring Boot/스프링 부트 핵심 가이드

[SpringBoot] 5.6-7 Swagger와 Logback

nayonsoso 2023. 7. 30. 22:20
Summary :
Swagger은 xxxx인 API 문서 작성툴
Logback은 xxxx 하게 하는 로그 출력 형식 

🔍 목차

5.6 REST API 명세를 문서화하는 방법 : Swagger
5.7 로깅 라이브러리 : Logback

 

📌 5.6 REST API 명세를 문서화하는 방법 : Swagger

API 명세란?

  • API를 개발하면 명세를 관리해야 함
  • 명세란 해당 API가
    1) 어떤 로직을 수행하는지
    2) 이 로직을 수행하기 위해 어떤 값을 요청하는지
    3) 이에 따른 응답값으로는 무엇을 받을 수 있는지
    를 정리한 자료
  • API는 개발 과정에서 계속 변경되므로 작성한 명세 문서도 주기적인 업데이트가 필요함
    하지만 명세 작업은 번거롭고, 어플리케이션과 명세가 일치하지 않는 문제가 발생할 수도 있음
    이 같은 문제를 해결하기 위해 등장한 것이 바로 Swagger' 라는 오픈소스 프로젝트

Swagger을 사용하는 방법

① Swagger 의존성 추가

  • 주요 사양 
    - SpringFox Swagger 2 : 프로젝트의 응답, 요청, 예시 등의 정보를 JSON 쌍으로 만들어줌
    - SpringFox UI : Swagger 2를 통해 만든 JSON 쌍을 상호작용하기 좋은 웹페이지로 만들어줌
    - SpringFox Data REST : @Entity와 @Repository를 찾아 엔티티에 대한 사양 정보를 추가로 문서화함
    - SpringFox Bean Validator : Swagger 문서화를 진행하면서 Bean Validation Annotation이 적용된 내용에 대한 정보를 추가로 저장함
  • io.springfox:springfox-boot-starter 를 추가하면 위 의존성들을 한번에 추가해줄 수 있음
  • 이후 URI에 /swagger-ui/ 를 추가하여 들어가면, 스웨거 문서 화면을 볼 수 있음

주식 프로젝트의 스웨거 화면

② Swagger 설정 Configuration 클래스

  • config 패키지 하단에 스웨거 설정 클래스를 만들어서 설정 코드를 작성해야 함
  • 이름은 일반적으로 관례적으로 SwaggerConfig로 설정
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    private static final String API_NAME = "주식 프로젝트";
    private static final String API_VERSION = "0.0.1";
    private static final String API_DESCRIPTION = "주식 배당금 정보를 불러오는 프로젝트입니다.";
    
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                // 보여주고 싶은 컨트롤러만 보여줄 수 있음
                .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
                // .paths(PathSelectors.any("/read/**")) : /read/로 시작하는 API만 보여줄 수 있음
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title(API_NAME)
                .version(API_VERSION)
                .description(API_DESCRIPTION)
                .build();
    }
}

 

③ 컨트롤러 매서드 / 모델 설명 추가 → 자세한 내용은 스웨거 꾸밀 때 해도 될듯 (공부는 지금 당장 필요한 만큼만!)

 @ApiOperation(value = "GET 메서드 예제", notes = "@RequestParam을 활용한 GET Method")
 GetMapping(value="/request1")
 public String getRequestParam1(
 	@ApiParam(value = "이름", required = true) @RequestParam String name,
	@ApiParam(value = "이메일", required = true) @RequestParam String email,
	@ApiParam(value = "회사", required = true) @RequestParam String organization) {
	return name + " " + email + + organization;
 }

 

Swagger 대표 어노테이션

Swagger가 사용하는 대표 어노테이션으론, @ApiOperation와 @ApiParam가 있다.

  • @ApiOperation : 대상 API의 설명을 작성하기 위한 어노테이션
  • @ApiParam : 매개변수에 대한 설명 및 설정을 위한 어노테이션

출처 : swagger 적용 (velog.io)

Swagger의 Try it out 기능

  • Swagger에서는 API 명세 관리 뿐 아니라 직접 통신도 시도할 수 있다.
  • 위 화면에서 [Try it out] 버튼을 클릭하고 각 항목의 값을 기입한 다음 [Execute] 버튼을 누르면
    완성된 요청 URL과 그에 대한 결괏값도 받아볼 수 있다.

 

📌 5.7 로깅 라이브러리 : Logback

로깅(logging)이란 애플리케이션이 동작하는 동안 시스템의 상태나 동작 정보를 시간순으로 기록하는 것을 의미합니다.
로깅은 개발 영역 중 '비기능 요구사항'에 속합니다. 즉, 사용자나 고객에게 필요한 기능은 아니라는 의미 입니다.
하지만 로깅은 디버깅하거나 개발 이후 발생한 문제를 해결할 때 원인을 분석하는 데 꼭 필요한 요소입니다.

자바 진영에서 가장 많이 사용되는 로깅 프레임워크는 Logback입니다.
Logback이란 log4j 이후에 출시된 로깅 프레임워크로서 slf4j'를 기반으로 구현됐으며,
과거에 사용되던 log4j에 비해 월등한 성능 을 자랑합니다.
또한 스프링 부트의 spring-boot-starter-web 라이브러리 내부에 내장돼 있어
별도의 의존성을 추가하지 않아도 사용할 수 있습니다.

Logback은 크게 5개의 로그 레벨(TRACE, DEBUG, INFO, WARN, ERROR)을 설정할 수 있습니다.

  • ERROR: 로직 수행 중에 시스템에 심각한 문제가 발생해서 애플리케이션의 작동이 불가능한 경우를 의미합니다.
  • WARN: 시스템 에러의 원인이 될 수 있는 경고 레벨을 의미합니다.
  • INFO: 애플리케이션의 상태 변경과 같은 정보 전달을 위해 사용됩니다.
  • DEBUG: 애플리케이션의 디버깅을 위한 메시지를 표시하는 레벨을 의미합니다.
  • TRACE: DEBUG 레벨보다 더 상세한 메시지를 표현하기 위한 레벨을 의미합니다.

실제 운영 환경과 개발 환경에서 각각 다른 출력 레벨을 설정해서 로그를 확인할 수 있습니다.

 

저작자표시