CoLabor : Swagger UI 설정 및 문제 해결 방법

Swagger UI

Swagger UI는 API 문서를 자동으로 생성하고 시각화하여 개발자와 사용자 모두에게 편리한 인터페이스를 제공합니다. 

---

1. build.gradle 파일 수정

Swagger를 사용하려면 프로젝트에 필요한 의존성을 추가해야 합니다. CO-LOBOR 프로젝트에서는 다음과 같이 설정했습니다:

dependencies {
    // Other dependencies...

    // Springdoc OpenAPI 의존성 추가
    implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.1.0'
}

빌드 명령 실행

의존성을 프로젝트에 반영하려면 아래 명령어를 실행합니다:

./gradlew build

---

2. Swagger 기본 설정 (application.properties)

Swagger UI를 프로젝트에 연결하려면 다음 설정을 application.properties 파일에 추가합니다:

# Swagger 관련 설정
springdoc.api-docs.path=/api-docs
springdoc.swagger-ui.path=/swagger-ui.html

이 설정을 통해 Swagger UI는 http://localhost:8080/swagger-ui.html 경로에서 제공되며, /api-docs 경로에서 OpenAPI 명세서를 JSON 형식으로 확인할 수 있습니다.

---

3. Swagger UI 접속 확인

Spring Boot 프로젝트를 실행한 후 Swagger UI에 접속하여 올바르게 설정되었는지 확인할 수 있습니다. 실행 명령어는 아래와 같습니다:

./gradlew bootRun

프로젝트가 실행된 후 브라우저에서 다음 URL로 이동합니다:

http://localhost:8080/swagger-ui.html

Swagger UI 화면이 나타나면 설정이 완료된 것입니다.

---

4. Swagger 어노테이션 활용법

Swagger 어노테이션은 API 문서를 더 직관적으로 작성할 수 있도록 돕습니다. CO-LOBOR 프로젝트에서 자주 사용한 어노테이션은 다음과 같습니다:

• @Tag: 컨트롤러 전체에 대한 설명을 제공합니다.
• @Tag(name = "Company", description = "Company Management APIs")
• @Operation: 각 API 메소드에 대한 설명을 추가합니다.
• @Operation(summary = "Get all companies", description = "Retrieve all registered companies")
• @Parameter: API 파라미터에 대한 설명을 추가합니다.
• @Parameter(name = "id", description = "Company ID", required = true)
• @ApiResponses: 응답 코드와 그 의미를 명시합니다.
• @ApiResponses(value = { @ApiResponse(responseCode = "200", description = "Successful retrieval"), @ApiResponse(responseCode = "404", description = "Company not found"), @ApiResponse(responseCode = "500", description = "Server error") })

이 어노테이션들을 적절히 사용하면 API 문서가 더 직관적이고 이해하기 쉬워집니다.

---

참고 및 문제 해결

1. Swagger UI가 로드되지 않을 때
   • 브라우저에서 http://localhost:8080/swagger-ui.html에 접속되지 않으면 application.properties의 경로 설정을 확인하십시오.
   • Spring Boot 버전과 의존성 버전이 호환되는지 확인합니다.
2. API 명세가 비어 있을 때
   • 컨트롤러에 적절한 어노테이션이 추가되었는지 확인하십시오. (@RestController, @RequestMapping 등)
   • @Operation 어노테이션을 각 메소드에 추가하여 설명을 명시합니다.
3. 의존성 충돌
   • 프로젝트에 다른 Swagger 라이브러리가 포함되어 있다면 제거하고 springdoc-openapi를 사용하십시오.

---

이 설정 과정과 문제 해결 팁을 따라하면 Swagger UI를 성공적으로 설정하고 활용할 수 있습니다.
CO-LOBOR 프로젝트에서는 이를 통해 효율적인 API 개발과 문서화를 구현했습니다.