[ Swagger ] SpringBoot 3.x 환경 + Swagger 3 이해 및 적용 (1)

 

 

---

 

 

✅  스웨거 ( Swagger ) 알아보기

 

 

1) 스웨거 ( Swagger ) 란 ?

 

-  RESTful API를 설계 , 구축 , 문서화 , 테스트하는데 사용되는 오픈소스 소프트웨어 프레임워크

   ( = API를 개발 / 관리 하는 과정을 효율적으로 만들어주는 도구이다. )

 

 

-  자동화된 API 문서 생성

•  특정 어노테이션을 추가하면 API 문서가 자동으로 생성

•  단순 텍스트 문서가 아니고, 직접 API를 호출하고 결과를 확인할 수 있는 인터페이스 제공

•  시간이 절약되고 문서의 정확성이 높다.

 

 

-  다양한 프레임워크 지원

•  Spring , Node.js , Python 등 다양한 프레임워크와 통합되어 사용 가능

 

 

-  주요 기능

•  API 설계  :  API의 엔드포인트 , 요청 / 응답 데이터 형식 , 인증방법 등 명확하게 정의 가능

•  API 문서 생성  :  정의된 정보를 바탕으로 HTML 형식의 API 문서 자동으로 생성

•  API 테스트  :  문서 내에서 API를 호출하고 결과 확인 가능

 

 

-  장점 및 주의점

•  개발 생산성 향상 ( API 개발 및 문서작성 시간 단축 )

•  API 품질 향상 ( API 설계 단계부터 문제점 파악 및 수정 가능 )

•  API 유지보수 향상 ( API 변경 시 , 문서를 자동으로 업데이트 하여 유지보수 비용 절감 )

 

 

-  공식 사이트

https://swagger.io/

API Documentation & Design Tools for Teams | Swagger

 

 

---

 

 

 

2) Swagger 사용법 및 사용 예시

 

💡  Swagger 3

-  openAPI Specification (OAS) 3.0 기반

※  OAS
-  API를 기술하는 표준화된 형식으로 JSON 또는 YAML로 API 의 엔드포인트 , 요청 , 응답
   인증 , 데이터 모델등을 기술

-  주요 특징
•  JSON Schema 를 기반으로 더욱 정확하고 상세한 모델 표현 가능
•  GET , POST , PUT , DELETE 외에도 다양한 HTTP 메서드 지원
•  경로 변수 , 쿼리 파라미터 , 헤더 , 쿠키 등 다양한 파라미터를 정의하고 검증 가능
•  다양한 응답 코드 및 응답 데이터 형식을 정의 가능하여 API 사용자에게 더욱 명확한 정보 제공


💡  Swagger UI
-  API 문서를 시각적으로 표현하고, 웹 인터페이스에서 API를 테스트할 수 있는 도구
-  사용자는 API 명세에 따라 API 호출 쉽게 실행


💡  Swagger Edit
-  API 정의 작성 , 편집 , 검증하는데 사용하는 도구
-  OAS 3를 기반으로 YAML 또는 JSON 형식으로 API 명세 작성 가능

 

 

 

 

-  Swagger 3 와 SpringBoot 통합

 

•  의존성 주입 필요

// build.gradle 의 dependencies {} 블록에 의존성 주입

dependencies {
	// Swagger UI
	implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.6.0'                   
}

 

 

 

 

※  Swagger 라이브리러리 종류 및 비교

 

라이브러리	특징	SpringBoot 호환성	Open API 버전
SpringFox Swagger 2	•  Spring 기반 어플리케이션 용 •  자동 Swagger 2.0 문서 생성 •  최근 업데이트 중단	Spring Boot 2.x 까지	Swagger 2
SpringDoc OpenAPI UI	•  SpringBoot 어플리케이션 용 •  자동 OpenAIP 3 문서 생성 •  활발한 유지보수	Spring Boot 1.x , 2.x	Swagger 3
SpringDoc OpenAPI Starter WebMVC UI	•  SpringBoot 3.x 버전 용 •  WebMVC 애플리케이션 지원 •  Swagger UI 통합	Spring Boot 3.x	Swagger 3

 

 

 

 

-  SpringDoc OpenAPI Starter WebMVC UI 주요 어노테이션

 

어노테이션	설명	사용 위치
@OpenAPIDefinition	•   API 문서의 전체적인 정보(= 제목, 설명, 버전 등 ) 를 제공 •  info / servers / components 속성	클래스 레벨
@Operation	•  API 엔드포인트에 대한 상세정보 제공 •  summary / description / tags 속성	메서드 레벨
@Tag	•  OpenAPI에서 그룹화(카테고리)를 정의	클래스 또는 인터페이스 레벨
@Parameter	•  .API 요청 파라미터 세부정보 정의	메서드 파라미터 레벨
@RequestBody	•  API  요청 본문(Body) 설명 추가	메서드 파라미터 레벨
@RequestHeader	•  API 요청 헤더(Header) 정보 문서화	메서드 파라미터 레벨
@ApiResponse	•  API 응답에 대한 설명 추가 •  상태코드 , 설명 , 응답 스키마 등 정의	메서드 레벨
@Schema	•  데이터 모델 클래스 또는 스키마 정보 정의	클래스 또는 필드 레벨

 

 

 

 

-  SpringDoc OpenAPI Starter WebMVC UI 환경 설정 세팅하기

 

 

•  개발환경

💡 환경 설정
-  Java  :  17
-  SpringBoot Version  :  3.4.1
-  빌드관리도구  :  Gradle 8.7
-  Swagger  :  3
-  SpringDoc OpenAPI Starter WebMVC UI  :  2.6.0
-  IDE  :  IntelJ 2023.1.7

 

 

•  의존성 주입 ( build.gradle )

// Swagger 의존성 주입
implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.6.0'

 

 

•  Swagger 설정 Class 파일 만들기 ( SwaggerConfig )

💡 SwaggerConfig 클래스 파일
-  Swagger로 구성하는 API 문서의 제목 , 버전 , 설명에 대해 설정 ( 전체적인 API 문서의 설정 담당 )
-  OpenAPI 설정
-  Swagger UI 설정

 

package com.spring.blogCrudApi.config;

import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SwaggerConfig {

    @Bean
    public OpenAPI openAPI() {
        Info info = new Info()
                .title("Swagger 연습용 Board API Document")
                .version("v0.0.1")
                .description("Swagger 연습용 게시판 API 명세서입니다.");
        return new OpenAPI()
                .components(new Components())
                .info(info);
    }
}

 

 

 

•  application.properties 설정

# Swagger Spring UI Setting
// 특정 패키지 컨트롤러만 스캔
springdoc.packages-to-scan=com.spring.blogCrudApi		
// API가 생성 및 소비하는 기본 미디어 타입 지정
springdoc.default-consumes-media-type=application/json;charset=UTF-8
springdoc.default-produces-media-type=application/json;charset=UTF-8
// OpenAPI 문서 생성을 위한 캐싱 설정 ( true = 비활성화 )
springdoc.cache.disabled=true
// OpenAPI 명세 문서의 경로 설정( 기본값 = /v3/api-docs )
springdoc.api-docs.path=/api-docs/json
// API 그룹화를 활성화
springdoc.api-docs.groups.enabled=true
// Swagger UI 활성화 여부
springdoc.swagger-ui.enabled=true
// Swagger UI 경로 설정 ( 기본값 = /Swagger-ui.html )
springdoc.swagger-ui.path=/practice-ui.html
// 태그 & 엔드포인트 알파벳순으로 정렬
springdoc.swagger-ui.tags-sorter=alpha
springdoc.swagger-ui.operations-sorter=alpha

 

 

 

---

 

 

3) Controller 적용

 

 

-  Postman으로 테스트 해보았던 Restful API 에 적용해보기로 한다.

•  아래 게시글을 참고

 

https://baby9235.tistory.com/132

[ API ] 간단 Restful CRUD API 포스트맨 테스트 ( SpringBoot + Gradle + MyBatis + Mysql )

 

 

-  Controller 소스

 

※  @Tag 어노테이션

•  SpringDoc OpenAPI 에서 특정 API 엔드포인트를 그룹화하고 설명화하기 위해 사용

•  name 속성 :  태그의 이름을 지정

•  description 속성 :  태그에 대한 간략한 설명 작성

 

※ @Operation 어노테이션

•  API 메서드에 대한 설명을 제공

•  summary 속성:  API 메서드에 대한 간단한 요약 설명

•  description 속성 :  API 메서드에 대한 상세한 설명

 

※  @ApiResponse 어노테이션

•  API 메서드 실행결과에 대한 응답 상태코드와 설명 , 응답데이터의 스키마를 정의

•  responseCode 속성 :  HTTP 응답상태 코드를 나타낸다. ( ex : 200 성공 , 404 Not Found )

•  description 속성 :  해당 응답 상태 코드에 대한 설명

•  content 속성 :  응답 데이터의 콘텐츠 타입과 스키마를 정의

 

※ @Parameter 어노테이션

•  REST API의 요청 파라미터에 대한 상세한 정보 제공

•  description 속성  :  파라미터에 대한 설명

•  name 속성  :  파라미터의 이름 명시적으로 지정 ( 보통 @RequestParam 의 value 속성과 동일시 한다. )

•  example 속성  :  파라미터의 예시값 제공

 

※ @Hidden 어노테이션

•  API나 API의 일부 요소를 Swagger UI에 표시하지 않도록 한다. 즉, API 문서에서 제외하여 외부에 노출하지 않는것

•  테스트용 API, 보안상 민감한 API, 더이상 사용하지 않는 API 등에 사용될 수 있습니다.

•  사용 위치에 따라 클래스 , 메서드 , 파라미터를 숨길 수 있습니다.

 

package com.spring.blogCrudApi.controller;

import com.spring.blogCrudApi.dto.BoardDto;
import com.spring.blogCrudApi.service.BoardService;
import io.swagger.v3.oas.annotations.Hidden;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.apache.ibatis.annotations.Param;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;

import java.util.List;
import java.util.Map;
import java.util.Objects;


@Tag(name = "Board-Controller", description = "Board CRUD API 엔드포인트")
@RestController
public class BoardController {

    private final BoardService boardService;

    @Autowired
    public BoardController(BoardService boardService) {
        this.boardService = boardService;
    }

    /**
     * Restful API Get 메서드
     * @param userId
     * @return
     */
    @GetMapping("/board")
    @Operation(summary = "게시글 조회", description = "게시글을 전체 조회 혹은 아이디로 조회 합니다.")
    @ApiResponse(responseCode = "200", description = "조회 성공", content = @Content(schema = @Schema(implementation = BoardDto.class)))
    public List<BoardDto> boardList(@Parameter(description = "사용자 아이디") @RequestParam (value = "userId", required = false) String userId) {

        if(userId == null ) {
            return boardService.selectAllBoardList();
        }

        return boardService.selectListByUserId(userId);
    }

    /**
     * Restful API POST 메서드
     * @param boardDto
     * @return
     */
    @PostMapping("/board")
    @Operation(summary = "게시글 등록", description = "게시글을 등록합니다.")
    @ApiResponse(responseCode = "200", description = "등록 성공")
    public Map<String, Object> createBoard(@RequestBody @Schema(implementation = BoardDto.class) BoardDto boardDto) {

        return boardService.insertBoard(boardDto);
    }

    /**
     * Restful API PUT  메서드
     * @param seq
     * @param boardDto
     * @return
     */
    @PutMapping("/board/{seq}")
    @Operation(
            summary = "게시글 수정",
            description = "게시글을 수정합니다. 요청 본문에는 수정할 게시글의 데이터, 경로 변수로 수정할 게시글의 글번호를 전달합니다.",
            responses = {
                    @ApiResponse(responseCode = "200", description = "수정 성공"),
                    @ApiResponse(responseCode = "400", description = "잘못된 요청. 요청 데이터가 유효하지 않거나 필수 데이터 누락"),
                    @ApiResponse(responseCode = "404", description = "수정하려는 게시글을 찾을 수 없음"),
                    @ApiResponse(responseCode = "500", description = "서버 오류")
            },
            parameters = {
                    @Parameter(name = "seq", description = "수정할 게시글의 고유 글번호", required = true, example = "1")
            }
    )
    public Map<String, Object> updateBoard(@PathVariable int seq, @RequestBody @Schema(implementation = BoardDto.class) BoardDto boardDto) {

        boardDto.setSeq(seq);
        return boardService.updateBoard(boardDto);
    }

    /**
     * Restful API DELETE 메서드
     * @param seq
     * @return
     */
    @DeleteMapping("/board/{seq}")
    @Hidden
    @Operation(summary = "게시글 삭제", description = "게시글을 삭제합니다. 경로 변수로 삭제할 게시글의 글번호를 전달합니다.")
    public Map<String, Object> deleteBoard(@PathVariable int seq) {

        return boardService.deleteBoard(seq);
    }
}

 

 

 

---

 

 

4) DTO 적용

 

-  DTO소스

 

※  @Schema 어노테이션

•  API 모델의 속성( property )에 대한 상세한 정보를 제공

•  속성에 대한 설명 , 예시 값 , 필수 여부 , 기본값 등 정보 제공

 

package com.spring.blogCrudApi.dto;

import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;

@Data
public class BoardDto {

    @Schema(description = "게시글 고유 번호", example = "1")
    private int seq;

    @Schema( description = "게시글 제목", example = "스웨거예시게시글")
    private String boardTitle;

    @Schema( description = "게시글 내용", example = "스웨거에 대해서 공부하는중이다.")
    private String boardContent;

    @Schema( description = "사용자 아이디", example = "백엔드개발자1")
    private String userId;

}

 

 

 

---

 

 

5) Swagger 실행 및 결과 보기

 

-  서버 실행 + 지정한 경로로 접근

💡 서버 실행 및 지정한 경로 접근
-  springdoc.swagger-ui.path 속성값으로 설정한 /practice-ui.html 경로 접근
-  http://localhost:8080/practice-ui.html 경로로 접근하면 default  값인 http://localhost:8080/swagger-ui.html 로
   리다이렉트 됩니다.

 

 

 

 

 

 

👉  해당 경로로 Swagger 를 통한 API 명세서가 나오는것을 확인할 수 있다. 

         다음 게시물을 통해서 Swagger 에 대해 좀 더 알아야 할 내용과 테스트하는 방법도 살펴볼 수

         있도록 하겠다.