Spring에 Swagger 도입하기

목차

• 서론
• 본론
  
  • spring 프로젝트 생성
  • library 사이트 문서 확인
  • library 설치
  • 화면 확인
  • 간단한 사용
• 첨언
• 소스코드

 

서론

---

Swagger는 RESTful API를 설계, 문서화 및 시각화하는 도구이다. 주로 개발자와 API 사용자 간의 소통을 촉진하고 API의 이해도를 높이는 데 사용된다. 이를 통해 API의 사용 방법, 엔드포인트, 요청 및 응답 형식 등을 명확하게 문서화하여 개발 및 통합 과정을 단순화할 수 있다. 그래서 문서화 하기 편한 swagger를 도입하기 위해 spring에 springdoc라고하는 라이브러리를 사용하여 swagger를 도입하는 과정을 설명하고 기록하고자한다.

 

본론

---

spring 프로젝트 생성

https://start.spring.io/ 를 방문해 기본 스프링 프로젝트를 생성한다. 기본적인 웹서버를 동작하기 위해 Spring Web Dependency를 추가하였다.

 

다운받은 프로그램의 헬스체크를 하는모습 정상적으로 작동한다.

 

library 사이트 문서 확인

https://springdoc.org를 방문해 swagger를 편하게 설치할 수 있는 오픈소스 라이브러리 springdoc를 다운을 받아보자.

 

 

목차 2번 Getting Started 를 들어가 보니 프로젝트 관리 및 빌드도구인 Maven xml문법으로 의존성(dependency)를 가져오는 방법이 적혀있다. 나는 gradle을 사용하니 google에 검색해 dependency를 가져오자. 

 

library 설치

구글에 검색하니 3번째 Mvn Repository라는 사이트가 있었고 이 사이트에서 gradle dependeny를 가져오는 문법을 확인할 수 있었다. 이를 내 프로젝트에 붙여넣기 하자.

1. build.gradle 에 붙여넣기 한 후
2. 코끼리 버튼을 눌러서 다시 빌드를 하자.

 

화면 확인

기본 url인 /swagger-ui/index.html 에 접속해보면 swagger 화면이 정상적으로 작동하는것을 확인할 수 있다.

 

간단한 사용

hello 라는 GET 요청을 하면

"{'data' : 'hello-world' }" 라는 payload를 주는 간단한

api만들어 보았다.

 package com.swagger.example.hello;

import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/hello")
public class HelloController {

    @GetMapping
    public ResponseEntity get(){
        return ResponseEntity.ok("{'data' : 'hello-world' }");
    }
}

 

swagger에서 통신성공하여 http STATUS 200과 "{'data' : 'hello-world' }" 데이터를 표현하는 모습

첨언

이 문서는 SpringBoot 3.x,  Java17 이상에서 원활하게 작동한다.

 

소스코드

https://github.com/MeotJH/swagger-example