[Spring Boot] 한국어기초사전 API 연동하기

왔다 정보리·2024년 4월 27일

백엔드에서 살아남기

목록 보기

3/5

한국어기초사전 오픈 API

한국어기초사전의 검색 플랫폼을 공개하여 다양하고 재미있는 서비스 및 애플리케이션을 개발할 수 있도록 오픈한 API이다. 한국어기초사전에 구축된 양질의 사전 정보를 개인 또는 기관에서 오픈 API를 이용해 자유롭게 이용할 수 있다! 나 역시 프로젝트를 진행하던 중, 사전 정보를 받아야 할 일이 생겨 한국어기초사전 오픈 API를 사용하게 되었다.

오픈 API 연동을 위한 사전 준비

한국어기초사전 오픈 API를 사용하기 위해서는 먼저 오픈 API 사용 신청을 해야 한다. 사용 신청은 한국어 기초 사전 홈페이지에 들어가서 할 수 있다.

오픈 API 사용 신청 화면

사용 신청은 이메일 입력만 하면 된다. 정책을 확인하고 이메일을 입력하면 이메일로 인증키가 도착한다. 서비스를 요청하기 위해서는 반드시 인증키가 필요하며, 서비스 요청은 하루에 50,000건으로 제한되어 있으니 주의해야 한다.

참고로 오픈 API는 사전 검색 오픈 API와 사전 내용 오픈 API 이렇게 두 개가 있다. 나는 단어의 뜻을 알아야 했기 때문에 사전 검색 오픈 API만 사용하였다.

API 연동

1. API 연동을 위한 정보를 확인한다

요청 URL, Request Parameter, Response field가 홈페이지에 자세히 설명되어 있다.

사전 검색 오픈 API 요청 URL
https://krdict.korean.go.kr/api/search

Request Param

Request Params	타입	설명	필수 / 선택
key	String	인증키	필수
q	String	검색어	필수
part	String	검색 대상	선택
translated	String	다국어 번역 여부 (y, n)	선택
advanced	String	자세히 찾기 여부	선택
method	String	검색 방식	선택

advanced 이후의 파라미터를 사용하기 위해서는 반드시 advanced를 y로 선택해야 한다.
많은 파라미터 중에 내가 사용할 파라미터만 골라서 작성하였다.

Response field (공통 Response)

필드	타입	필수/선택	설명
channel	-	필수	결과
title	String	필수	한국어 기초 사전 검색 오픈 API 제목
link	String	필수	한국어 기초 사전 URL
description	String	필수	오픈 API 서비스 설명
lastBuildDate	DateTime	필수	검색 결과를 생성한 시간
total	Integer	필수	검색된 전체 어휘 개수
start	Integer	필수	검색 결과 시작 번호
num	Integer	필수	검색 결과로 제공하는 어휘 개수

Response field (검색 출력 결과)

필드	타입	필수/선택	설명
item	-	필수	개별 검색 결과
target_code	Integer	필수	식별 코드
word	String	필수	표제어
sup_no	Integer	필수	동형어 번호
origin	String	선택	원어
pronunciation	String	선택	발음
word_grade	String	선택	어휘 등급
pos	String	필수	품사
link	String	필수	사전 내용 보기 URL
sense	String	필수	개별 의미를 포함하는 컨테이너
sense_order	Integer	필수	개별 의미 순번
definition	String	필수	뜻풀이
translation	String	선택	개별 의미
trans_word	String	선택	표제어 번역
trans_dfn	String	선택	뜻풀이 번역

Response field도 마찬가지로 사용할 필드만 골라서 작성하였다.

2. DTO를 생성한다

API 호출을 위한 조건을 모두 확인하였다면 실제로 코드를 작성하면 된다.

다음은 서버에 요청을 보내기 위한 Request DTO이다. 추후에 url 작성을 쉽게 하기 위해 getParameter 함수를 만들어주었다.

public class MeansReq {
    private String key;
    private String q;
    private String part;
    private String translated;
    private String advanced;
    private String method;

    public MeansReq(String key, String q) {
        this.key = key;
        this.q = q;
        this.part = "word";
        this.translated = "n";
        this.advanced = "y";
        this.method = "exact";
    }

    public String getParameter() {
        return "?key=" + this.key +
                "&q=" + this.q +
                "&part=" + this.part +
                "&translated=" + this.translated +
                "&advanced=" + this.advanced +
                "&method=" + this.method;
    }
}

다음은 XML을 Json으로 파싱하기 위해 만든 Response DTO이다. Response field를 활용하여 작성하였다.

public class MeansRes {
    private Channel channel;
}

public class Channel {
    private String description;
    private List<Item> item;
    private Long lastBuildDate;
    private String link;
    private int num;
    private int start;
    private String title;
    private int total;
}

public class Item {
    private String link;
    private String pos;
    private List<Sense> sense;
    private int sup_no;
    private int target_code;
    private String word;
}

public class Sense {
    private int sense_order;
    private String definition;
}

3. Controller를 구현한다

사용자의 API 호출을 처리하기 위한 Controller를 구현한다.

@GetMapping("/means")
public BaseResponse<GetMeanRes> getMeans(@RequestParam("word") String word) throws BaseException, IOException {
    if(word.isBlank()) {
        return new BaseResponse<>(BaseResponseStatus.INVALID_PARAMETERS);
    }

    return new BaseResponse<>(new GetMeanRes(word, openAPIService.getMeans(word)));
}

쿼리 파라미터로 검색할 단어를 받았다. 전달받은 단어가 없는 경우 예외를 반환하였다.

4. Service를 구현한다

실제로 로직을 처리할 Service를 구현한다.

@Transactional
public String getMeans(String word) throws BaseException, IOException {
    String baseUrl = "https://krdict.korean.go.kr/api/search";
    String encodedWord = URLEncoder.encode(word, StandardCharsets.UTF_8);

    MeansReq req = new MeansReq(key, encodedWord);
    StringBuilder result = new StringBuilder();

    // URL 설정
    URL url = new URL(baseUrl + req.getParameter());
    HttpURLConnection urlConnection = (HttpURLConnection) url.openConnection();

    // 접속
    urlConnection.setRequestMethod("GET");
    urlConnection.connect();

    BufferedReader bufferedReader = new BufferedReader(new InputStreamReader(urlConnection.getInputStream(), StandardCharsets.UTF_8));
    String returnLine;
    while ((returnLine = bufferedReader.readLine()) != null) {
        result.append(returnLine);
    }

    // JSON으로 변환
    JSONObject jsonObject = XML.toJSONObject(result.toString());

    ObjectMapper mapper = new ObjectMapper().configure(FAIL_ON_UNKNOWN_PROPERTIES, false);
    mapper.setVisibility(PropertyAccessor.FIELD, JsonAutoDetect.Visibility.ANY);
    mapper.configure(DeserializationFeature.ACCEPT_SINGLE_VALUE_AS_ARRAY, true);

    // MeansRes에 매핑
    MeansRes meansRes = mapper.readValue(jsonObject.toString(), MeansRes.class);
    System.out.println(meansRes);

    if (meansRes.getChannel().getItem().isEmpty()) {
        throw new BaseException(BaseResponseStatus.INVALID_WORD);
    }

    // DB에 뜻 저장
    String mean = meansRes.getChannel().getItem().get(0).getSense().get(0).getDefinition();
    openAPIRepository.save(Word.of(word, mean));

    return mean;
}

MeansReq req = new MeansReq(key, encodedWord);의 key는 한국어기초사전 홈페이지에서 발급받은 인증키를 넣어주면 된다. 위 코드에서 알아야 할 부분은 다음과 같다.

String encodedWord = URLEncoder.encode(word, StandardCharsets.UTF_8);를 통해 단어를 인코딩한다. 나는 이렇게 인코딩하지 않으면 400 에러가 발생하면서 뜻을 검색할 수 없었다.
Json으로 변환하기 위해 JSONObject를 사용한다.
검색한 단어에 대한 뜻이 존재하지 않으면 존재하지 않는 단어라는 예외를 반환한다.

나머지 부분은 서버에 접속하고 응답을 받아오기 위한 코드이다. 각자의 상황에 맞춰 변형해서 사용하면 된다.

홈페이지에 워낙 자세하게 설명이 되어 있어 어렵지 않게 API를 연동할 수 있었다. 단어 뜻이 필요한 경우에는 한국어기초사전 오픈 API를 유용하게 사용할 수 있을 것 같다!