[인턴/안심등하원서비스] springdoc을 이용해서 Swagger-ui 세팅 👾 (feat. gradle, application.yml 환경)

스프링부트 프로젝트에 Swagger-ui 적용하기

ko웹사이트 프로젝트를 어느정도 끝내고 선임님께 넘겼다.

그리고 곧이어 시작된 새로운 프로젝트...

 

사실 React 로 프론트엔드 개발하다가 백엔드 API 개발해서 연결해보고 싶어서 ㅋㅋㅋ

급하게 스프링부트 환경 세팅하고 회원가입, 로그인, 토큰 발급, 재발급 등 API를 작성했다. 

 

그런데 문득 이걸 회사에 다시 드리려면, 따로 문서를 만들어두는게 좋을 것 같아서 Swagger-ui 세팅을 해둬야겠다고 생각했다.

 

예~전에 django 로 프로젝트 했을 때 스웨거 적용을 해뒀었는데, 

이번에 데보션영 springboot 프로젝트에는 따로 스웨거 적용 안하고 노션에 작성하고 공유했어서.. 

 

새로운걸 해볼 생각에 신났다 🔥🔥🔥

 

그렇게 구글링을 진행했는데, 오호라!

 

데보션!!!

 

데보션 글이 눈에 띄었다.

물론 원래 첫번째 게시글은 읽어주는게 국룰이기 때문에 ^^ 읽었음.

 

그리고 들어갔는데, 헐랭~~~🥹❤️

저번에 인터뷰를 정성스럽게 진행해주신 "배기도" 프로님의 글이었다...

 

우와ㅏ아ㅏㅏㅏ

 

너무 반가워서 당장 이 글을 보고 해봐야겠다고 생각했다 ㅋㅋㅋ

 

https://devocean.sk.com/experts/techBoardDetail.do?ID=164919

［Spring-API First Develope 연재-1］ Spring-docs를 이용한 Swagger API 문서 자동생성

 

---

 

Swagger-ui 적용 방법

프로님의 글과 같은 경우엔, Maven (pom.xml) 을 사용하셨고 application.properties 가 설정파일 이었다. 

 

** 나의 스프링부트 환경

- gradle 사용 : build.gradle

- 설정파일 : application.yml 

 

그래서 프로님께서 작성해주신 코드를 내 환경에 맞게 수정해서 사용하였다. 

아래는 내가 작성한 코드 예시 이다. 

 

build.gradle

dependencies 부분에 swagger ui 의존성을 추가한다.

plugins {
	id 'java'
	id 'org.springframework.boot' version '3.4.0'
	id 'io.spring.dependency-management' version '1.1.6'
}

...

dependencies {
	implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
	implementation 'org.springframework.boot:spring-boot-starter-security'
	implementation 'org.springframework.boot:spring-boot-starter-web'
	implementation 'io.github.cdimascio:dotenv-java:3.0.0'
	implementation 'io.jsonwebtoken:jjwt-api:0.12.3'

	compileOnly 'org.projectlombok:lombok'

	developmentOnly 'org.springframework.boot:spring-boot-devtools'

	runtimeOnly 'com.mysql:mysql-connector-j'
	runtimeOnly 'io.jsonwebtoken:jjwt-impl:0.12.3'
	runtimeOnly 'io.jsonwebtoken:jjwt-jackson:0.12.3'

	annotationProcessor 'org.projectlombok:lombok'

	// Swagger UI 의존성 추가
	implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.1.0'

	testImplementation 'org.springframework.boot:spring-boot-starter-test'
	testImplementation 'org.springframework.security:spring-security-test'
	testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
}

tasks.named('test') {
	useJUnitPlatform()
}

 

 

application.yml 

맨 아래에 있는 springdoc 부분을 추가하면 된다. 

spring:
  application:
    name: kidsnotiBack
  datasource:
    url: ${DB_URL}
    username: ${DB_USERNAME}
    password: ${DB_PASSWORD}
    driver-class-name: com.mysql.cj.jdbc.Driver
  jpa:
    hibernate:
      ddl-auto: update
    show-sql: true
    properties:
      hibernate.dialect: org.hibernate.dialect.MySQL8Dialect
  sql:
    init:
      mode: always

server:
  port: 8080

jwt:
  secret: ${JWT_SECRET}
  expiration: 3600000

springdoc:
  api-docs:
    path: /api-docs
  swagger-ui:
    path: /swagger-ui.html

 

 

Swagger Anotation 추가

Swagger 페이지에 내가 작성한 API 에 대해서 더 구체적인 설명을 달아두기 위해 사용한다.

우선 나는 Operation Annotation 만 작성해두었다📝

package com.jordy.kidsnotiBack.controller;

import com.jordy.kidsnotiBack.dto.LoginRequest;
import com.jordy.kidsnotiBack.dto.LoginResponse;
import com.jordy.kidsnotiBack.dto.SignupRequest;
import com.jordy.kidsnotiBack.entity.Token;
import com.jordy.kidsnotiBack.entity.User;
import com.jordy.kidsnotiBack.service.TokenService;
import com.jordy.kidsnotiBack.service.UserService;
import io.swagger.v3.oas.annotations.Operation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/auth")
public class AuthController {
    @Autowired
    private UserService userService;

    @Autowired
    private TokenService tokenService;

    @Operation(summary = "회원가입", description = "사용자가 회원가입을 할 수 있는 API")
    @PostMapping("/signup")
    public ResponseEntity<User> signup(@RequestBody SignupRequest request) {
        User user = userService.register(request);
        return ResponseEntity.ok(user);
    }

    @Operation(summary = "로그인", description = "사용자가 로그인할 수 있는 API. 로그인 시 액세스 토큰과 리프레시 토큰을 반환.")
    @PostMapping("/login")
    public ResponseEntity<LoginResponse> login(@RequestBody LoginRequest request) {
        User user = userService.validateUser(request.getUserId(), request.getPassword())
                .orElseThrow(() -> new RuntimeException("Invalid username or password"));

        LoginResponse response = tokenService.generateLoginResponse(user);
        return ResponseEntity.ok(response);
    }

    @Operation(summary = "리프레시 토큰 발급", description = "리프레시 토큰을 이용해 새로운 액세스 토큰을 발급받는 API")
    @PostMapping("/refresh-token")
    public ResponseEntity<Token> refreshToken(@RequestBody String refreshToken) {
        Token newToken = tokenService.refreshToken(refreshToken);
        return ResponseEntity.ok(newToken);
    }
}

 

 

---

 

작성한 API 리스트 확인 

프로젝트를 실행시키면, 설정해둔 URL 에서 Swagger UI 적용된 API 문서를 확인할 수 있다.

 

Swagger UI URL : http://localhost:8080/swagger-ui.html

 

 

API Docs URL (JSON 형식으로 API 명세서 제공): http://localhost:8080/api-docs

 

 

프로님 글 덕분에 무사히 적용완료!

감사합니다 🥹🔥