DataGSM OpenAPI SDK Java / Kotlin

dependencies {
  implementation("com.github.themoment-team:datagsm-openapi-sdk-java:1.3.0")
}

repositories {
  maven { url = uri("https://jitpack.io") }
}

import team.themoment.datagsm.sdk.openapi.DataGsmOpenApiClient;

// 기본 설정으로 클라이언트 생성
DataGsmOpenApiClient client = DataGsmOpenApiClient.builder("your-api-key-here").build();

// 커스텀 Base URL 설정 (선택사항)
DataGsmOpenApiClient clientWithCustomUrl = DataGsmOpenApiClient.builder("your-api-key-here")
  .baseUrl("https://api.datagsm.com") // 설정하지 않는다면 공식 Base URL 사용
  .build();

import team.themoment.datagsm.sdk.openapi.client.StudentApi;
import team.themoment.datagsm.sdk.openapi.model.*;

// 요청 파라미터 설정
StudentApi.StudentRequest request = new StudentApi.StudentRequest()
  .grade(1) // 1학년
  .classNum(1) // 1반
  .page(0) // 첫 번째 페이지
  .size(50); // 페이지당 50명

// API 호출
StudentResponse response = client.students().getStudents(request);

// 결과 처리
for (Student student : response.getStudents()) {
  System.out.printf("%s - %s%n", student.getName(), student.getEmail());
}

import team.themoment.datagsm.sdk.openapi.client.NeisApi;
import team.themoment.datagsm.sdk.openapi.model.*;
import java.time.LocalDate;

// 오늘 날짜의 급식 조회
NeisApi.MealRequest request = new NeisApi.MealRequest()
  .date(LocalDate.now());

List<Meal> meals = client.neis().getMeals(request);

// 급식 데이터 출력
for (Meal meal : meals) {
  System.out.println(meal.getMealType() + ":");
  for (String menu : meal.getMealMenu()) {
      System.out.println(" - " + menu);
  }
}

// 학생 목록 조회
StudentResponse students = client.students().getStudents(request);

// 특정 학생 조회
Student student = client.students().getStudent(1L);

import team.themoment.datagsm.sdk.openapi.model.EnrollmentFilter;

// 재학생만 조회
StudentApi.StudentRequest onlyEnrolledRequest = new StudentApi.StudentRequest()
  .enrollmentFilter(EnrollmentFilter.onlyEnrolled());

// 졸업생 포함 조회
StudentApi.StudentRequest includeGraduatesRequest = new StudentApi.StudentRequest()
  .enrollmentFilter(EnrollmentFilter.detailed().includeGraduates(true));

// 자퇴생 포함 조회
StudentApi.StudentRequest includeWithdrawnRequest = new StudentApi.StudentRequest()
  .enrollmentFilter(EnrollmentFilter.detailed().includeWithdrawn(true));

// 서버 기본값 사용 (파라미터 미전송)
StudentApi.StudentRequest defaultRequest = new StudentApi.StudentRequest();

// 동아리 목록 조회
ClubResponse clubs = client.clubs().getClubs(request);

// 특정 동아리 조회
ClubDetail club = client.clubs().getClub(1L);

// 프로젝트 목록 조회
ProjectResponse projects = client.projects().getProjects(request);

// 특정 프로젝트 조회
Project project = client.projects().getProject(1L);

// 급식 데이터 조회
List<Meal> meals = client.neis().getMeals(request);

// 학사일정 조회
List<Schedule> schedules = client.neis().getSchedules(request);

try {
  StudentResponse students = client.students().getStudents(request);
  // 성공적인 응답 처리
} catch (UnauthorizedException e) {
  // API 키 갱신 필요
  logger.error("API key expired or invalid", e);
  renewApiKey();
} catch (ForbiddenException e) {
  // 권한 범위 부족
  logger.warn("Insufficient permissions", e);
  notifyUserAboutPermissions();
} catch (RateLimitException e) {
  // Rate limit 초과 - 적절한 재시도 로직 구현 필요
  logger.warn("Rate limit exceeded", e);
  // 실제로는 exponential backoff 등의 재시도 전략 구현 권장
} catch (BadRequestException e) {
  // 잘못된 요청 파라미터
  logger.error("Invalid request parameters: {}", e.getMessage());
  validateParameters();
} catch (ServerErrorException e) {
  // 서버 오류
  logger.error("Server error occurred", e);
  notifyAdmin();
} catch (DataGsmException e) {
  // 기타 예외
  logger.error("API error: {}", e.getMessage(), e);
}

// Java의 try-with-resources 사용
try (DataGsmOpenApiClient client = DataGsmOpenApiClient.builder("your-api-key").build()) {
  StudentResponse students = client.students().getStudents(request);
  // 클라이언트 사용
} // 블록이 끝나면 자동으로 리소스 정리

package com.example.config;

import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import team.themoment.datagsm.sdk.openapi.DataGsmOpenApiClient;

@Configuration
public class DataGsmConfig {

  @Bean
  @ConfigurationProperties(prefix = "datagsm.api")
  public DataGsmProperties dataGsmProperties() {
      return new DataGsmProperties();
  }

  @Bean
  public DataGsmOpenApiClient dataGsmClient(DataGsmProperties properties) {
      return DataGsmOpenApiClient.builder(properties.getKey())
          .baseUrl(properties.getBaseUrl())
          .build();
  }

  public static class DataGsmProperties {
      private String key;
      private String baseUrl;

      public String getKey() { return key; }
      public void setKey(String key) { this.key = key; }
      public String getBaseUrl() { return baseUrl; }
      public void setBaseUrl(String baseUrl) { this.baseUrl = baseUrl; }
  }

}

package com.example.service;

import org.springframework.stereotype.Service;
import team.themoment.datagsm.sdk.openapi.DataGsmOpenApiClient;
import team.themoment.datagsm.sdk.openapi.client.StudentApi;
import team.themoment.datagsm.sdk.openapi.model.*;

import java.util.List;

@Service
public class SchoolDataService {

  private final DataGsmOpenApiClient dataGsmClient;

  public SchoolDataService(DataGsmOpenApiClient dataGsmClient) {
      this.dataGsmClient = dataGsmClient;
  }

  public List<Student> getStudentsByClass(int grade, int classNum) {
      StudentResponse response = dataGsmClient.students().getStudents(
          new StudentApi.StudentRequest()
              .grade(grade)
              .classNum(classNum)
              .size(50)
      );
      return response.getStudents();
  }

}

import team.themoment.datagsm.sdk.openapi.DataGsmOpenApiClient;
import team.themoment.datagsm.sdk.openapi.client.*;
import team.themoment.datagsm.sdk.openapi.model.*;

import java.time.LocalDate;
import java.util.List;

public class Main {
  public static void main(String[] args) {
      // try-with-resources로 자동 리소스 관리
      try (DataGsmOpenApiClient client = DataGsmOpenApiClient.builder("your-api-key-here").build()) {

          // 학생 데이터 조회
          StudentResponse students = client.students().getStudents(
              new StudentApi.StudentRequest()
                  .grade(1)
                  .classNum(1)
                  .size(10)
          );

          // 결과 출력
          for (Student student : students.getStudents()) {
              System.out.printf("%s (%s) - %s%n",
                  student.getName(),
                  student.getStudentNumber().orElse("N/A"),
                  student.getEmail()
              );
          }

          // 급식 데이터 조회
          List<Meal> meals = client.neis().getMeals(
              new NeisApi.MealRequest().date(LocalDate.now())
          );

          // 급식 출력
          for (Meal meal : meals) {
              System.out.println(meal.getMealType() + ":");
              for (String menu : meal.getMealMenu()) {
                  System.out.println("  - " + menu);
              }
          }

      } catch (UnauthorizedException e) {
          System.err.println("인증 오류: API 키가 유효하지 않습니다.");
          e.printStackTrace();
      } catch (RateLimitException e) {
          System.err.println("요청 제한 초과: 잠시 후 다시 시도해주세요.");
          e.printStackTrace();
      } catch (DataGsmException e) {
          System.err.println("API 오류 발생: " + e.getMessage());
          e.printStackTrace();
      } catch (Exception e) {
          System.err.println("예상치 못한 오류 발생: " + e.getMessage());
          e.printStackTrace();
      }
  }

}

public class Main {
  public static void main(String[] args) {
      // 환경 변수에서 API 키 로드
      String apiKey = System.getenv("DATAGSM_API_KEY");

      if (apiKey == null || apiKey.isEmpty()) {
          System.err.println("환경 변수 DATAGSM_API_KEY가 설정되지 않았습니다.");
          System.exit(1);
      }

      try (DataGsmOpenApiClient client = DataGsmOpenApiClient.builder(apiKey).build()) {
          // API 사용
      }
  }

}