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

[JayongLee]

🗞️ 연관된 이슈

🔥 이슈번호

• Resolved : docs: Swagger 적용 #131

✅ 작업 내용

• API 명세서 (Open API) / Spring Docs / Swagger

📸 스크린샷 (선택)

체크리스트 ✅

• 코드가 정상적으로 컴파일되나요?
• merge할 브랜치의 위치를 확인했나요?
• 테스트 코드를 작성하셨나요?

기타

[gemini-code-assist]

Summary of Changes

Hello @JayongLee, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

이 Pull Request는 프로젝트에 OpenAPI(Spring Docs, Swagger)를 통합하여 API 명세서를 자동 생성하고 시각화하는 것을 목표로 합니다. 이를 통해 개발자들이 API 엔드포인트를 더 쉽게 이해하고 테스트할 수 있도록 지원하며, API 문서의 일관성과 유지보수성을 향상시킵니다. 주요 API 컨트롤러에 문서화 어노테이션을 추가하고 전역 설정을 통해 명세서의 가독성을 높였습니다.

Highlights

• OpenAPI 통합: Springdoc OpenAPI 라이브러리를 프로젝트에 추가하여 API 문서화를 시작했습니다.
• Swagger UI 설정: application.yml 파일에 Swagger UI 경로 및 정렬 기준 등 기본 설정을 추가했습니다.
• API 컨트롤러 문서화: 주요 컨트롤러(계좌, 환율, 송금, 수수료, 거래)에 @tag 및 @operation 어노테이션을 적용하여 API 그룹화 및 각 엔드포인트에 대한 상세 설명을 추가했습니다.
• OpenAPI 전역 설정: OpenApiConfig 클래스를 신규 생성하여 API 문서의 제목, 설명, 버전, 연락처 및 서버 정보를 전역적으로 설정했습니다.

Changelog

• build.gradle
  • Springdoc OpenAPI Starter WebMVC UI 의존성이 추가되었습니다.
• src/main/java/org/creditto/core_banking/domain/account/controller/AccountController.java
  • Swagger 관련 import 문이 추가되었습니다.
  • @tag 어노테이션이 클래스 레벨에 추가되어 'Account' API 그룹을 정의했습니다.
  • 각 엔드포인트 메서드에 @operation 어노테이션이 추가되어 API 요약 및 설명을 제공했습니다.
• src/main/java/org/creditto/core_banking/domain/exchange/controller/ExchangeController.java
  • Swagger 관련 import 문이 추가되었습니다.
  • @tag 어노테이션이 클래스 레벨에 추가되어 'Exchange' API 그룹을 정의했습니다.
  • 각 엔드포인트 메서드에 @operation 어노테이션이 추가되어 API 요약 및 설명을 제공했습니다.
• src/main/java/org/creditto/core_banking/domain/overseasremittance/controller/OneTimeRemittanceController.java
  • Swagger 관련 import 문이 추가되었습니다.
  • @tag 어노테이션이 클래스 레벨에 추가되어 'Remittance (One-time)' API 그룹을 정의했습니다.
  • processRemittance 메서드에 @operation 어노테이션이 추가되어 API 요약 및 설명을 제공했습니다.
• src/main/java/org/creditto/core_banking/domain/overseasremittance/controller/RemittanceQueryController.java
  • Swagger 관련 import 문이 추가되었습니다.
  • 불필요한 RequestParam import 문이 제거되었습니다.
  • @tag 어노테이션이 클래스 레벨에 추가되어 'Remittance (Query)' API 그룹을 정의했습니다.
  • 각 엔드포인트 메서드에 @operation 어노테이션이 추가되어 API 요약 및 설명을 제공했습니다.
• src/main/java/org/creditto/core_banking/domain/regularremittance/controller/RegularRemittanceController.java
  • Swagger 관련 import 문이 추가되었습니다.
  • @tag 어노테이션이 클래스 레벨에 추가되어 'Remittance (Scheduled)' API 그룹을 정의했습니다.
  • 각 엔드포인트 메서드에 @operation 어노테이션이 추가되어 API 요약 및 설명을 제공했습니다.
• src/main/java/org/creditto/core_banking/domain/remittancefee/controller/RemittanceFeeController.java
  • Swagger 관련 import 문이 추가되었습니다.
  • @tag 어노테이션이 클래스 레벨에 추가되어 'Remittance Fee' API 그룹을 정의했습니다.
  • calculateRemittanceFee 메서드에 @operation 어노테이션이 추가되어 API 요약 및 설명을 제공했습니다.
• src/main/java/org/creditto/core_banking/domain/transaction/controller/TransactionController.java
  • Swagger 관련 import 문이 추가되었습니다.
  • @tag 어노테이션이 클래스 레벨에 추가되어 'Transaction' API 그룹을 정의했습니다.
  • getTransactions 메서드에 @operation 어노테이션이 추가되어 API 요약 및 설명을 제공했습니다.
• src/main/java/org/creditto/core_banking/global/config/OpenApiConfig.java
  • OpenAPI 전역 설정을 위한 새로운 OpenApiConfig 클래스가 추가되었습니다.
• src/main/resources/application.yml
  • Springdoc OpenAPI 관련 설정(api-docs 경로, swagger-ui 경로, operation 및 tag 정렬)이 추가되었습니다.

Ignored Files

• Ignored by pattern: .github/workflows/** (2)
  • .github/workflows/CD.yml
  • .github/workflows/CI.yml

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

이 PR은 Spring Docs와 Swagger를 사용하여 API 문서를 적용하는 변경 사항을 담고 있습니다. 전반적으로 각 컨트롤러에 @Tag와 @Operation 어노테이션을 추가하여 API 명세를 잘 정의하고 있습니다. OpenApiConfig와 application.yml 설정도 적절합니다.

몇 가지 컨트롤러에서 @Operation 어노테이션이 추가되면서 기존 Javadoc 주석이 중복되는 경우가 발견되었습니다. 코드 중복을 피하고 장기적인 유지보수성을 높이기 위해 중복되는 Javadoc을 제거하는 것을 제안하는 리뷰 의견을 남겼습니다. 이를 통해 API 문서가 한 곳(Swagger 어노테이션)에서 관리되도록 할 수 있습니다.