[Spring][개념]📄 Swagger를 활용한 REST API 문서화의 모든 것

✨ Swagger를 통한 REST API 문서화에 대한 설명

Swagger는 REST API의 문서화를 자동화하여 프론트엔드와 백엔드 개발 간의 협업을 효율적으로 지원하는 도구입니다. Swagger의 사용과 그 이점을 단계별로 설명하겠습니다.

---

1️⃣ 프론트엔드와 백엔드 개발자의 역할 분리

• 프론트엔드 개발자: 사용자와 상호작용하는 화면(UI)을 개발하고, 데이터 표시와 조작을 위한 로직을 작성합니다.
• 백엔드 개발자: 데이터베이스 연동, 비즈니스 로직, 데이터 처리 등 서버 측의 로직을 구현하며, 프론트엔드와의 데이터 통신을 위한 API를 설계합니다.

🎯 이처럼 역할이 분리되면 백엔드 개발자가 제공하는 API를 프론트엔드 개발자가 참고하여 화면에 필요한 데이터를 가져와야 합니다.

---

2️⃣ 프론트엔드 개발자의 API 의존성

프론트엔드 개발자는 백엔드에서 제공하는 API에 의존해 데이터를 처리합니다. API 문서가 없다면 요청해야 할 URL, 파라미터, 응답 형식 등을 알기 어렵기 때문에 API 문서가 필수적입니다.

예시: 사용자 정보를 보여주는 화면을 구현할 때, 프론트엔드 개발자는 사용자 데이터를 얻기 위한 API의 엔드포인트 URL, 요청 방식, 응답 형식 등을 알고 있어야 합니다.

---

3️⃣ API 변경 시 발생하는 불편함

개발 중에는 API가 자주 변경됩니다. 새로운 기능 추가, 기존 기능 수정, 예외 처리 추가 등의 이유로 API가 업데이트될 때마다 문서 또한 최신으로 유지해야 합니다.

• 문서화 작업의 부담: 문서를 수작업으로 관리할 경우 누락이나 실수가 발생하기 쉽습니다.
• 협업의 비효율성: 문서가 최신 상태가 아니라면, 프론트엔드 개발자는 API의 변경 사항을 인지하지 못해 개발 효율이 떨어질 수 있습니다.

---

4️⃣ Swagger의 사용 이유

Swagger는 API를 자동으로 문서화해주는 도구로, API 변경 사항을 자동 반영하여 프론트엔드와 백엔드 간 협업을 크게 향상시킵니다.

• 자동화된 문서 갱신: Swagger는 코드에 기반하여 자동으로 API 문서를 생성하기 때문에, 백엔드 코드가 변경될 때마다 문서도 자동으로 최신 상태로 갱신됩니다.
• 실시간 확인 가능: 프론트엔드 개발자는 Swagger를 통해 API의 최신 정보를 확인할 수 있으며, 요청 형식이나 응답 예시도 바로 확인할 수 있습니다.
• 팀원 간의 효율적인 공유: API 문서가 자동화되어 실시간으로 갱신되기 때문에, 팀원들이 일관된 정보에 접근할 수 있어 문서 업데이트에 따른 혼란이 줄어듭니다.

🌐 효율성 증가: Swagger는 API 변경 사항을 체계적으로 관리할 수 있어, 수동 문서화로 인한 오류를 줄이고, 유지보수를 간편하게 합니다.

---

✨ Swagger의 기능과 장점에 대한 설명

Swagger는 API 문서화를 자동화하고, 개발자들이 API와 더 쉽게 상호작용할 수 있도록 돕는 강력한 도구입니다. 각 기능과 장점을 아래와 같이 설명하겠습니다.

---

1️⃣ Swagger의 간단한 설정

• Swagger는 프로젝트 API를 자동으로 문서화해주며, 웹 페이지 형태로 API 목록을 보여줍니다.
• 코드에 간단한 설정만 추가하면, Swagger는 모든 API를 자동으로 수집해 개발자가 쉽게 확인하고 테스트할 수 있는 문서를 생성합니다.

🎯 효과: Swagger를 통해 API에 대한 정보가 쉽게 제공되어, 모든 개발자들이 간편하게 API 목록을 확인하고 각 API의 세부 사항을 명확히 알 수 있습니다.

---

2️⃣ Controller에 정의된 URL 확인

• Swagger는 프로젝트 내의 모든 API URL을 한 페이지에서 한눈에 볼 수 있도록 합니다.
• 각 HTTP 메소드(GET, POST, PUT, DELETE 등)와 함께 URL이 표시되어, 어떤 API가 어떤 방식으로 호출되는지 명확하게 보여줍니다.

📍 효과: 프로젝트 내에서 어떤 API가 어떤 경로에서 호출되는지 직관적으로 이해할 수 있어, 개발자 간의 협업이 수월해집니다.

---

3️⃣ API 명세와 설명 제공

• Swagger는 각 API의 입력 파라미터, 응답 형식, 설명 등을 포함한 API 명세를 제공합니다.
• 개발자는 각 API가 어떤 데이터를 입력으로 받고, 어떤 형식으로 응답하는지 명확하게 파악할 수 있으며, API의 동작을 설명하는 추가 주석을 통해 API의 목적을 쉽게 이해할 수 있습니다.

📝 효과: 개발자들이 각 API의 동작과 파라미터를 쉽게 이해할 수 있으며, API 사용 중 발생할 수 있는 혼란과 실수를 방지할 수 있습니다.

---

4️⃣ 직접 테스트 가능

• Swagger UI는 직접 API를 테스트할 수 있는 기능을 제공합니다.
• 브라우저에서 API를 호출하여 실시간으로 응답 데이터를 확인할 수 있고, 다양한 파라미터 값을 변경해가며 API가 올바르게 작동하는지 테스트할 수 있습니다.

🚀 효과: 개발 초기 단계와 유지보수 단계에서 API의 정상 작동 여부를 즉시 확인할 수 있어, 디버깅과 오류 수정이 용이해집니다.

---

📌 Spring 프로젝트 적용을 위한 springdoc-openapi

• 링크(https://springdoc.org/)는 springdoc-openapi 라이브러리의 공식 사이트로 연결되며, 이 라이브러리는 Spring 프로젝트에 Swagger를 손쉽게 적용할 수 있도록 돕습니다.
• springdoc-openapi는 Spring Boot 환경에서 Swagger 설정을 간단히 추가할 수 있어, Spring 기반의 프로젝트에 Swagger UI 기능을 쉽게 도입할 수 있습니다.

---

🔧 SwaggerConfiguration.java 파일 설정

📌 클래스 설정

• @Configuration 어노테이션이 붙어 있습니다. 이 클래스는 Spring에서 설정 클래스로 인식되며, Swagger 관련 설정이 적용됩니다.

📌 OpenAPI 객체 생성

• @Bean 어노테이션을 통해 openAPI() 메서드가 정의되어 있습니다. 이 메서드는 OpenAPI의 기본 정보를 설정합니다.
  • Info info 객체를 생성하여 API의 타이틀, 설명, 버전, 연락처 정보 등을 설정합니다.
  • title("Project API 명세서"): API의 이름을 나타내며, 프로젝트 명세서라는 의미입니다.
  • description: Swagger UI에 표시될 추가 정보로, HTML 태그를 포함해 로고와 안내 텍스트를 추가합니다.
  • contact: API 담당자 이름, 이메일, URL을 설정하여 연관된 정보도 표시합니다.
  • return: 설정된 info 객체가 포함된 OpenAPI 인스턴스를 반환하여 Swagger UI에 표시됩니다.

@Configuration
public class SwaggerConfiguration {
    
    @Bean
    public OpenAPI openAPI() {
        Info info = new Info()
                .title("Project API 명세서")
                .description("<img src='https://example.com/logo.png' style='width: 50px;'/> API 명세서입니다. ")
                .version("v1.0.0")
                .contact(new Contact().name("개발팀").email("devteam@example.com").url("https://example.com"));
        
        return new OpenAPI().info(info);
    }
}

---

📂 API 그룹 설정

📌 관리자 API 그룹

• publicApi() 메서드는 GroupedOpenApi를 통해 관리자용 API 그룹을 만듭니다.
  • group("admin-api"): 이 API 그룹의 이름을 "admin-api"로 설정하여, Swagger UI에서 관리자용 API를 쉽게 구분할 수 있도록 합니다.
  • pathsToMatch("/admin/**"): /admin/로 시작하는 경로만 이 그룹에 포함시켜 관리자가 사용하는 엔드포인트들만 표시됩니다.

@Bean
public GroupedOpenApi publicApi() {
    return GroupedOpenApi.builder()
            .group("admin-api")
            .pathsToMatch("/admin/**")
            .build();
}

📌 사용자 API 그룹

• userApi() 메서드는 사용자용 GroupedOpenApi를 생성합니다.
  • group("user-api"): 이 API 그룹의 이름을 "user-api"로 설정하여 일반 사용자가 볼 수 있는 API 그룹을 표시합니다.
  • pathsToMatch("/user/**"): /user/로 시작하는 경로만 이 그룹에 포함되어 사용자용 엔드포인트들만 표시됩니다.

@Bean
public GroupedOpenApi userApi() {
    return GroupedOpenApi.builder()
            .group("user-api")
            .pathsToMatch("/user/**")
            .build();
}

---

🔧 AdminUserController 클래스

@RestController
@RequestMapping("/admin")
@CrossOrigin("*")
@Tag(name = "어드민 컨트롤러", description = "회원 목록과 상세보기, 등록, 수정, 삭제 등 전반적인 회원 관리를 처리하는 클래스")
public class AdminUserController {
    private static final Logger logger = LoggerFactory.getLogger(AdminUserController.class);

    private MemberService memberService;

    public AdminUserController(MemberService memberService) {
        this.memberService = memberService;
    }

📌 @RestController

• 해당 클래스가 REST API의 컨트롤러임을 나타냅니다. Spring에서 이 클래스를 RESTful 웹 서비스의 엔드포인트로 사용할 수 있도록 합니다.

📌 @RequestMapping("/admin")

• 클래스의 기본 경로를 /admin으로 설정합니다. 이 클래스에 정의된 모든 메서드는 /admin을 포함한 URL에서 호출됩니다.

📌 @CrossOrigin("*")

• CORS (Cross-Origin Resource Sharing) 설정으로, 모든 도메인에서 이 API에 접근할 수 있도록 허용합니다. 특정 도메인 제한 없이 외부 요청을 허용하려는 경우 사용합니다.

📌 @Tag 어노테이션

• @Tag(name = "어드민 컨트롤러", description = "회원 목록과 상세보기, 등록, 수정, 삭제 등 전반적인 회원 관리를 처리하는 클래스")
• Swagger 문서에서 이 컨트롤러에 대한 설명을 제공하는 역할을 합니다.
  • name: Swagger UI에서 컨트롤러의 이름을 표시합니다.
  • description: 회원 관리 기능에 대한 설명을 추가하여, 해당 컨트롤러가 어떤 역할을 수행하는지 설명합니다.

---

🔧 API 메서드 - 회원 목록 조회

    @Operation(summary = "회원목록", description = "회원의 <big>전체 목록</big>을 반환해 줍니다.")
    @ApiResponses(value = {
        @ApiResponse(responseCode = "200", description = "회원목록 OK!!"),
        @ApiResponse(responseCode = "404", description = "페이지없어!!"),
        @ApiResponse(responseCode = "500", description = "서버에러!!")
    })
    @GetMapping(value = "/user")
    public ResponseEntity<?> userList() {
        return ResponseEntity.ok("회원목록 리턴 call");
    }
}

📌 @Operation 어노테이션

• summary: API 엔드포인트의 간단한 요약을 제공합니다. 여기서는 "회원목록"으로 설정되어 있어, 이 API가 회원 목록을 제공하는 기능임을 나타냅니다.
• description: API의 상세 설명을 제공합니다. 이 설명은 Swagger UI에서 더 자세한 정보를 제공하며, HTML 태그를 사용하여 텍스트를 강조할 수도 있습니다.

📌 @ApiResponses 어노테이션

• 여러 @ApiResponse를 포함하여 API의 다양한 응답 코드와 그 설명을 정의합니다.
  • 각 응답 코드와 설명을 통해, 클라이언트가 요청에 대한 가능한 응답 상태를 쉽게 이해할 수 있습니다.

📌 @ApiResponse 어노테이션

• responseCode: HTTP 응답 코드를 지정합니다.
• description: 응답 코드에 대한 설명을 제공합니다.
  • 200: 요청이 성공했을 때의 메시지 "회원목록 OK!!".
  • 404: 리소스를 찾지 못했을 때의 메시지 "페이지없어!!".
  • 500: 서버 내부 오류가 발생했을 때의 메시지 "서버에러!!".

📌 @GetMapping(value = "/user")

• HTTP GET 요청을 받는 메서드이며, /admin/user 경로로 호출됩니다. 이 메서드는 회원 목록을 반환하는 기능을 담당합니다.

📌 userList 메서드

• ResponseEntity.ok("회원목록 리턴 call")을 반환하여, 회원 목록을 반환하는 API의 예제 응답을 나타냅니다. 실제 개발 환경에서는 데이터베이스에서 회원 목록을 가져와 반환할 것입니다.

---

🧾 @Schema 어노테이션 적용 (MemberDto 클래스)

@Schema(title = "MemberDto (회원정보)", description = "회원의 아이디, 비번, 이름을 가진 Domain Class")
public class MemberDto {

📌 @Schema 어노테이션 (클래스 수준)

• title: 클래스의 제목을 설정합니다. 여기서는 "MemberDto (회원정보)"로 설정하여 이 클래스가 회원 정보를 다루는 DTO임을 명확히 합니다.
• description: 이 클래스의 설명을 제공하여, Swagger 문서에 "회원의 아이디, 비번, 이름을 가진 Domain Class"라는 설명이 나타납니다. 이를 통해 이 DTO가 회원 관련 데이터를 담고 있음을 직관적으로 알 수 있습니다.

---

🧾 @Schema 어노테이션 (필드 수준) 각 필드별 설명

    @Schema(description = "회원아이디", requiredMode = Schema.RequiredMode.REQUIRED, example = "hissam")
    private String userId;

1. userId 필드
   • description: 필드에 대한 설명으로 "회원아이디"를 명시하여, Swagger UI에서 이 필드가 회원의 아이디임을 나타냅니다.
   • requiredMode: 이 필드를 필수 값으로 설정합니다. Schema.RequiredMode.REQUIRED를 사용하여, API 요청 시 반드시 포함되어야 하는 값임을 나타냅니다.
   • example: 예시 값 "hissam"을 추가하여, Swagger UI에서 API 테스트 시 참조할 수 있는 샘플 값을 제공합니다.

    @Schema(description = "회원이름", example = "홍길동")
    private String userName;

2. userName 필드
   • description: "회원이름"으로 필드에 대한 설명을 추가하여 이 필드가 사용자의 이름을 담고 있음을 명시합니다.
   • example: "홍길동"이라는 예시 값을 제공하여 Swagger UI에서 API 테스트 시 참고할 수 있습니다.

    @Schema(description = "회원비밀번호")
    private String userPwd;

3. userPwd 필드
   • description: "회원비밀번호"라는 설명을 추가하여, 이 필드가 사용자의 비밀번호를 담는 필드임을 명확히 합니다.

    @Schema(description = "이메일아이디")
    private String emailId;

    @Schema(description = "이메일도메인", defaultValue = "ssafy.com", example = "google.com")
    private String emailDomain;

4. emailId 및 emailDomain 필드
   • emailId 필드는 "이메일아이디"로 설명됩니다.
   • emailDomain 필드는 "이메일도메인"으로 설명되며, 추가적으로 기본 값과 예시 값을 제공합니다.
     • defaultValue: 기본 값을 "ssafy.com"으로 설정하여, 값이 지정되지 않았을 때 기본적으로 이 값을 사용하게 됩니다.
     • example: "google.com"이라는 예시 값을 설정하여 Swagger 문서에서 이 필드를 테스트할 때 참고할 수 있습니다.

    @Schema(description = "가입일", defaultValue = "현재시간")
    private String joinDate;
}

5. joinDate 필드
   • description: 이 필드를 "가입일"로 설명하여 가입 날짜를 담는 필드임을 명확히 합니다.
   • defaultValue: 기본 값을 "현재시간"으로 설정하여, 값이 주어지지 않은 경우 현재 시간이 기본으로 사용됨을 나타냅니다.