Docs: OpenAPI 적용 (Spring Docs, Swagger) / #131

.github/workflows/CI.yml

@@ -2,58 +2,24 @@ name: CI
 
 on:
   pull_request:
-    branches: [ "main", "dev" ]
+    branches: ["main", "dev"]
 
 jobs:
   build:
-    runs-on: self-hosted
+    runs-on: ubuntu-latest
 
     steps:
       - name: checkout
         uses: actions/checkout@v3
 
-      - name: .env 파일 생성
-        run: |
-
-          # .env 파일 생성
-          touch .env
-
-          # .env 파일 작성
-          echo "${{ secrets.ENV_FILE }}" >> .env
-
-          chmod 600 .env
-
-        shell: bash
-
-      - name: build 실행
-        run: |
-          chmod +x gradlew
-          ./gradlew clean build
-        shell: bash
-
-      - name: sonarqube
-        run: |
-          ./gradlew sonar \
-            -Dsonar.projectKey=${{ secrets.SONAR_PROJECT_NAME }} \
-            -Dsonar.host.url=${{ secrets.SONAR_HOST_URL }} \
-            -Dsonar.login=${{ secrets.SONAR_TOKEN }}
-
-        shell: bash
-
-      - name: SonarQube Quality Gate check
-        id: sonarqube-quality-gate-check
-        uses: sonarsource/sonarqube-quality-gate-action@master
+      - name: Set up JDK 17
+        uses: actions/setup-java@v4
         with:
-          pollingTimeoutSec: 600
-          scanMetadataReportFile: build/sonar/report-task.txt
-        env:
-          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
-          SONAR_HOST_URL: ${{ secrets.SONAR_HOST_URL }}
+          distribution: temurin
+          java-version: "17"
+          cache: gradle
 
-      - name: Cleanup
-        if: always()
+      - name: Run CI validation
         run: |
-          rm .env
-          rm -rf build
-          docker system prune -af --volumes
-        shell: bash
+          chmod +x gradlew
+          ./gradlew clean build --no-daemon

build.gradle

@@ -35,6 +35,7 @@ dependencies {
 	implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
     implementation 'org.springframework.security:spring-security-crypto'
 	implementation 'org.springframework.boot:spring-boot-starter-web'
+    implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.8.5'
     implementation 'org.springframework.boot:spring-boot-starter-data-redis'
     implementation 'org.redisson:redisson-spring-boot-starter:3.45.1'
     implementation 'io.micrometer:micrometer-tracing-bridge-brave'

src/main/java/org/creditto/core_banking/domain/account/controller/AccountController.java

@@ -1,65 +1,70 @@
 package org.creditto.core_banking.domain.account.controller;
 
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import org.creditto.core_banking.domain.account.dto.AccountCreateReq;
+import org.creditto.core_banking.domain.account.dto.AccountPasswordConfirmReq;
 import org.creditto.core_banking.domain.account.dto.AccountRes;
 import org.creditto.core_banking.domain.account.dto.AccountSummaryRes;
-import org.creditto.core_banking.domain.account.dto.AccountPasswordConfirmReq;
 import org.creditto.core_banking.domain.account.service.AccountService;
 import org.creditto.core_banking.global.response.ApiResponseUtil;
 import org.creditto.core_banking.global.response.BaseResponse;
 import org.creditto.core_banking.global.response.SuccessCode;
 import org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.annotation.*;
 
-import org.springframework.web.bind.annotation.GetMapping;
-import org.springframework.web.bind.annotation.PathVariable;
-import org.springframework.web.bind.annotation.RequestMapping;
-import org.springframework.web.bind.annotation.RestController;
-
 import java.math.BigDecimal;
 import java.util.List;
 
 @RestController
 @RequiredArgsConstructor
 @RequestMapping("/api/core/account")
+@Tag(name = "Account", description = "계좌 관련 API")
 public class AccountController {
 
     private final AccountService accountService;
 
+    @Operation(summary = "계좌 생성", description = "사용자 ID 기준으로 신규 계좌를 생성합니다.")
     @PostMapping("/{userId}")
     public ResponseEntity<BaseResponse<AccountRes>> createAccount(@RequestBody AccountCreateReq request,
                                                                   @PathVariable Long userId) {
         return ApiResponseUtil.success(SuccessCode.CREATED, accountService.createAccount(request, userId));
     }
 
+    @Operation(summary = "계좌 비밀번호 검증", description = "요청된 계좌 비밀번호 일치 여부를 검증합니다.")
     @PostMapping("/{accountId}/verify-password")
     public ResponseEntity<BaseResponse<Void>> verifyPassword(@PathVariable Long accountId,
                                                              @RequestBody AccountPasswordConfirmReq request) {
         accountService.verifyPassword(accountId, request.password());
         return ApiResponseUtil.success(SuccessCode.OK);
     }
 
+    @Operation(summary = "계좌 단건 조회", description = "계좌 ID로 계좌 정보를 조회합니다.")
     @GetMapping("/{accountId}")
     public ResponseEntity<BaseResponse<AccountRes>> getAccountByAccountId(@PathVariable Long accountId) {
         return ApiResponseUtil.success(SuccessCode.OK, accountService.getAccountById(accountId));
     }
 
+    @Operation(summary = "계좌 잔액 조회", description = "계좌 ID로 현재 잔액을 조회합니다.")
     @GetMapping("/{accountId}/balance")
     public ResponseEntity<BaseResponse<BigDecimal>> getAccountBalanceByAccountId(@PathVariable Long accountId) {
         return ApiResponseUtil.success(SuccessCode.OK, accountService.getAccountBalanceById(accountId));
     }
 
+    @Operation(summary = "계좌번호 조회", description = "계좌번호로 계좌 정보를 조회합니다.")
     @GetMapping(params = "accountNo")
     public ResponseEntity<BaseResponse<AccountRes>> getAccountByAccountNo(@RequestParam(name = "accountNo") String accountNo) {
         return ApiResponseUtil.success(SuccessCode.OK, accountService.getAccountByAccountNo(accountNo));
     }
 
+    @Operation(summary = "사용자 계좌 목록 조회", description = "사용자 ID로 보유 계좌 목록을 조회합니다.")
     @GetMapping(params = "userId")
     public ResponseEntity<BaseResponse<List<AccountRes>>> getAccountByClientId(@RequestParam(name = "userId") Long userId) {
         return ApiResponseUtil.success(SuccessCode.OK, accountService.getAccountByUserId(userId));
     }
 
+    @Operation(summary = "사용자 총 잔액 조회", description = "사용자 ID 기준 전체 계좌 수와 총 잔액을 조회합니다.")
     @GetMapping("/balance/total")
     public ResponseEntity<BaseResponse<AccountSummaryRes>> getTotalBalanceByUserId(@RequestParam(name = "userId") Long userId) {
         return ApiResponseUtil.success(SuccessCode.OK, accountService.getTotalBalanceByUserId(userId));

src/main/java/org/creditto/core_banking/domain/exchange/controller/ExchangeController.java

@@ -1,5 +1,7 @@
 package org.creditto.core_banking.domain.exchange.controller;
 
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import org.creditto.core_banking.domain.creditscore.service.CreditScoreService;
 import org.creditto.core_banking.domain.exchange.dto.*;
@@ -19,6 +21,7 @@
 @RestController
 @RequestMapping("/api/core/exchange")
 @RequiredArgsConstructor
+@Tag(name = "Exchange", description = "환율 및 우대환율 조회 API")
 public class ExchangeController {
 
     private final ExchangeService exchangeService;
@@ -29,6 +32,7 @@ public class ExchangeController {
      *
      * @return 성공 응답 및 최신 환율 정보 리스트
      */
+    @Operation(summary = "최신 환율 목록 조회", description = "지원 통화의 최신 환율 목록을 조회합니다.")
     @GetMapping
     public ResponseEntity<BaseResponse<Map<String, ExchangeRateRes>>> getExchangeRates() {
         return ApiResponseUtil.success(SuccessCode.OK, exchangeService.getLatestRates());
@@ -40,12 +44,14 @@ public ResponseEntity<BaseResponse<Map<String, ExchangeRateRes>>> getExchangeRat
      * @param currency 조회할 통화
      * @return 성공 응답 및 특정 통화 최신 환율 정보
      */
+    @Operation(summary = "통화별 환율 조회", description = "특정 통화의 최신 환율을 조회합니다.")
     @GetMapping("/{currency}")
     public ResponseEntity<BaseResponse<SingleExchangeRateRes>> getExchangeRate(@PathVariable String currency) {
         CurrencyCode currencyCode = CurrencyCode.from(currency);
         return ApiResponseUtil.success(SuccessCode.OK, exchangeService.getRateByCurrency(currencyCode));
     }
 
+    @Operation(summary = "우대환율 조회", description = "사용자와 통화 기준 우대환율 정보를 조회합니다.")
     @GetMapping("/preferential-rate/{userId}/{currency}")
     public ResponseEntity<BaseResponse<PreferentialRateRes>> getPreferentialRate(
             @PathVariable Long userId,

src/main/java/org/creditto/core_banking/domain/overseasremittance/controller/OneTimeRemittanceController.java

@@ -1,5 +1,7 @@
 package org.creditto.core_banking.domain.overseasremittance.controller;
 
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.validation.Valid;
 import lombok.RequiredArgsConstructor;
 import org.creditto.core_banking.domain.overseasremittance.dto.OverseasRemittanceRequestDto;
@@ -21,6 +23,7 @@
 @RestController
 @RequiredArgsConstructor
 @RequestMapping("/api/core/remittance")
+@Tag(name = "Remittance (One-time)", description = "일회성 해외송금 API")
 public class OneTimeRemittanceController {
 
     private final OneTimeRemittanceService oneTimeRemittanceService;
@@ -31,6 +34,7 @@ public class OneTimeRemittanceController {
      * @param request 송금에 필요한 정보(고객 ID, 수취인 정보, 금액 등)를 담은 DTO
      * @return 처리 결과를 담은 응답 DTO ({@link OverseasRemittanceResponseDto})
      */
+    @Operation(summary = "일회성 해외송금 요청", description = "사용자 ID 기준 일회성 해외송금을 실행합니다.")
     @PostMapping("/once/{userId}")
     public ResponseEntity<BaseResponse<OverseasRemittanceResponseDto>> processRemittance(
             @PathVariable Long userId,