[자바] 이클립스를 이용해 JAVA API 문서 만들기

API 란?

API (Application Programming Interface)
API는 응용 프로그램에서 사용할 수 있도록, 운영 체제나 프로그래밍 언어가 제공하는 기능을 제어할 수 있게 만든 인터페이스를 뜻한다.

출처 : steemit.com/kr/@yahweh87/it-api

 

 

 

 

자바에서 제공하는 API는 엄청 크고 방대해서 API문서를 통해 사용자들에게 사용법과 정보를 전달하고 있습니다.

자바를 개발하기 위해서 이 API 문서를 읽고 사용할 수 있어야 합니다.

 

자바 API 문서는 아래의 문서를 통해서 볼 수 있습니다.

[오라클 자바 api 문서]

 

docs.oracle.com/en/java/javase/11/docs/api/index.html

Overview (Java SE 11 & JDK 11 )

 

하지만 자바를 개발하는 어떤 팀이나 회사에서 직접 만든 소스코드가 있을 것입니다.

만약 팀에서 만든 클래스, 메서드, 인터페이스 등을 다른 팀이나 사람, 고객 등에게 사용법을 제공하려고 한다면 설명서가 필요할 것입니다.

코드를 개발한 팀에서도 사용자를 위한 설명서를 제공하려면 위의 자바 API 문서처럼 API문서를 작성해야 합니다.

이러한 문서작업은 귀찮고 힘든 일이지만, 이클립스로 이 작업을 자동화할 수 있습니다.

 

 

 

 

728x90

---

API 주석

다른 사람이 개발자의 코드(클래스, 메서드, 패키지)를 사용할 수 있도록 HTML 또는 XML 형식으로 설명을 작성한
주석입니다.

 

이 API 주석들은 나중에 API 문서를 자동으로 생성할 때 참조가 되는 부분입니다.

만약 코드를 배포하게 된다면 이 주석을 작성하는 버릇을 가지는 것이 좋습니다.

예를 들어 '팀 프로젝트' 또는 '아카이브 배포', '프레임워크', '솔루션 판매' 등 하면 필수입니다.

 

 

 

이클립스에서 본 Scanner.nextInt()

 

API 주석을 달면 위와 같이 코드 위에 마우스를 올리면 해당 메서드, 클래스에 설명을 볼 수 있습니다.

 

위의 사진과 같이 사용자도 직접 api 주석을 달아 확인할 수 있습니다.

 

 

---

 

API 주석을 작성하는 방법

이클립스 기준으로 설명합니다.
IntelliJ나 다른 IDE를 사용하시는 분들은 해당 IDE의 방법을 찾아보세요.

 

API 주석을 작성하는 방법은 간단합니다.

클래스, 메서드의 상단에 /**을 작성하고 ENTER를 치면 API 주석이 만들어집니다.

주석에 해당 코드의 설명을 작성하면 되겠습니다.

 

아래의 설명을 보며 차근차근 따라 해 봅시다.

 

맨 위에 보면 함수의 상단에 /**를 입력했습니다.

 

그 후 ENTER를 치면 이클립스에서 자동으로 API 주석을 작성해줍니다.

 

필요한 설명을 입력합니다.

 

 

 

---

API 문서 만들기

위처럼 함수, 메서드 등에 모두 API 주석을 입력했다면 API 문서로 만들 수 있습니다.

우리는 이클립스를 이용해서 API 문서를 만들지만,

API 문서작성은 실질적으로 JDK의 'javadoc.exe'를 이용해서 만들게 됩니다.

 

JDK폴더/bin/javadoc.exe

javadoc.exe 는 JDK폴더 ➡ bin ➡ javadoc.exe 에 있습니다.

이클립스는 이 javadoc.exe를 실행하여 API문서를 만듭니다.

 

---

 

이클립스로 API 문서 만드는 법

이클립스로 이동합니다.

 

 

Export

이클립스의 "Project Explorer" 창에 프로젝트를 오른쪽 클릭하여 Export를 합니다.

 

 

Export창에서 javadoc를 입력하면 javadoc가 나옵니다.

javadoc를 클릭하고 next를 눌러줍니다.

 

 

맨 위에 javadoc command는 javadoc.exe의 경로가 나옵니다.

자동으로 나오니 신경 쓰지 맙시다.

 

아래에는 "Select types for which Javadoc will be generated"를 보시면
프로젝트 리스트가 나오는데, API 문서를 만들 프로젝트를 선택합니다.

 

private, package, protected, public 등이 있는 접근 제한자가 있습니다.

어느 범위까지 문서로 추출할 건지 정할 수 있습니다.

• public을 선택하면 private, package, protected는 문서로 추출되지 않습니다.
• private를 선택하면 package, protected, public까지 모두 문서화됩니다.

API문서 저장 위치를 정하는 것은 필수입니다.

문서를 저장할 위치를 지정하고 다음을 누르면 되겠습니다.

 

 

Next를 누릅니다.

 

 

 

API Doc의 옵션을 선택하는 Dialog

API 문서 만드는데 몇 가지 옵션을 선택할 수 있는 창입니다.

저는 그냥 Next를 눌러서 다음으로 넘어갔습니다.

 

 

 

 

만약 소스코드를 UTF-8 기준으로 만든다면 VM option에 encoding 옵션을 넣어줘야 합니다.

만약에 소스가 UTF-8로 인코딩 되어 있다면 VM option에 다음 내용을 입력해야 합니다.

-locale ko_KR -encoding UTF-8 -charset UTF-8 -docencoding UTF-8

만약 UTF-8이 아니면 그냥 Finish를 누르면 되겠습니다.

 

 

만약 인코딩을 확인하지 않으면 이렇게 에러가 나옵니다.

 

 

소스코드 인코딩 확인방법

먼저 상단 메뉴의 Window -> Preferences를 클릭하여

Preferences 창으로 이동합니다

 

1. General 클릭

2. Content Types 클릭

3. Text를 펼치고 아래로 스크롤을 내려서 "JAVA Source File"을 찾습니다

 

 

Java Source File을 클릭하면 아래 Default encoding이 무엇으로 되어 있는지 확인할 수 있습니다.

만약에 UTF-8이면 위의 코드를 VM option에 입력한 후 Finish를 누르면 되겠습니다.

 

 

 

API 문서가 만들어지는 모습

 

---

만들어진 API 문서 확인하기

만들어진 위치에 html 형식으로 API 문서가 만들어져 있다.

지정한 위치로 이동하면 API 문서가 HTML형식으로 제작되어 있습니다.

index.html을 찾아 클릭하여 브라우저에서 열어봅니다.

 

 

API 문서를 찾아볼 수 있다.

클릭해서 들어가면 클래스에 API 주석으로 입력한 설명들이 다 추출되어 만들어진 모습을 볼 수 있습니다.

---

API 주석 태그

@author 이름	클래스나 인터페이스의 제작자 표시
@version 테스트	클래스나 인터페이스에서의 버전 정보
@param 매개변수 - 이름 설명	매개 변수에 대한 설명
@return 설명	메소드가 void를 리턴하거나 생성자가 아닌 경우를 제외하고 모두 사용해야 함
@exception or @throws	메소드가 발생시킬 수 있는 예외를 기술
@deprecated	다음 버전에서 폐기된 메소드를 알림
@serial	기본적으로 직렬화 할 수 있는 클래스의 멤버를 설명
@see	- 어떤 클래스, 인터페이스, 메소드, 생성자 혹은 URL에 대한 전후 참조 표시  - 분리된 줄에 링크가 생김
@since	Tag를 가진 객체가 언제 추가되었는지 명시
{@link #entity label}	메소드나 필드의 상호 참조에 대한 링크를 표시 문서 텍스트 안에 링크가 생김
{@doc-root}	문서에 대한 루트디렉토리에 대한 상대경로 지정

출처 : https://6kkki.tistory.com/1