OpenAPI 스펙을 지원하는 openapi-3.0 기능을 사용하여
REST API 문서를 생성할 수 있습니다. REST API를 문서화하고 공용 및 개인용 API를
지정한 후 어노테이션 스캐닝을 사용하도록 선택하고 웹 애플리케이션을 Liberty 서버에
배치하십시오. 그런 다음 인간 친화적인 사용자 인터페이스를 사용하는 브라우저에서 openapi-3.0에 의해 생성되는 API 문서를 볼 수 있습니다.
시작하기 전에
OpenAPI V3 스펙에 대해 학습하십시오. YAML 또는 JSON 파일을 사용하여 애플리케이션의
RESTful API를 문서화합니다.
이 태스크 정보
다음 샘플 애플리케이션을 사용하여 이러한 기능(예: 새 사용자 인터페이스,
어노테이션 및 프로그래밍 인터페이스)을 탐색할 수 있습니다.
프로시저
- OpenAPI 문서를 빌드하십시오.
여러 가지 방법으로 OpenAPIs를 문서화하고 빌드할 수 있습니다.
- Liberty 서버 구성에서 openapi-3.0 기능을 사용으로 설정하십시오.
- 기능 관리자에 openapi-3.0 기능을 추가하십시오.
<server>
<featureManager>
<feature>openapi-3.0</feature>
</featureManager>
</server>
- 옵션: OpenAPI 애플리케이션을 개인용으로 지정하십시오.
기본적으로 OpenAPI 문서는 공용입니다. 모든 사용자는 종종 인증없이 공용 API에
액세스할 수 있습니다. 공용 API는 /api/docs 자원에 문서화되어
있습니다.
API가 개인용으로 유지되도록 지정할 수 있습니다. 관리용 API는 일반적으로
개인용으로 유지됩니다. 보호용 비밀번호를 사용하는 개인용 API는
/ibm/api/docs 자원에 문서화되어 있습니다. 이 자원은 모든
개인용 API 및 모든 공용 API를 문서화합니다.
다음 두 가지 방법으로 웹 애플리케이션에 대한 개인용 API를 지정할 수 있습니다.
- public속성이 false로 설정된 서버 구성에서
webModuleDoc를 사용하십시오.
- openapi 요소를 추가하고 해당 enablePrivateURL
부울 속성을 true로 설정하십시오.
- 각 웹 애플리케이션에 대한 webModuleDoc 하위 요소를
추가하고 공용 API의 경우 public 부울 속성을 true로 설정하고 개인용 API의 경우 false로 설정합니다.
다음 예제는 airlines 애플리케이션 OpenAPI를 표시하고 airlinesAdmin
애플리케이션 OpenAPI의 노출을 사용 안함으로 설정합니다.
<openapi enablePrivateURL="true">
<webModuleDoc contextRoot="/airlines" public="true" />
<webModuleDoc contextRoot="/airlinesAdmin" public="false" />
</openapi>
기본적으로 webModuleDoc의 public
속성은 true로 설정됩니다. 이 구성은 개인용으로 유지하려는
애플리케이션을 사용 안함으로 설정하는 경우에만 필요합니다.
- API 설명의 벤더 확장 키워드를 사용하여 API를 개인용으로 지정하십시오.
- 서버 구성에 openapi 요소를 추가하고 해당
enablePrivateURL 부울 속성을 true로 설정하십시오.
- API 설명 문서 META-INF/openapi.yaml 파일 또는 지원되는
다른 형식의 파일에 x-ibm-private: true 키워드 및 값을 넣으십시오.
이 값은 API의 기본 가시성을 대체하며 이 값을 webModuleDoc
항목으로 대체할 수 있습니다.
- 옵션: 애플리케이션이 OpenAPI 문서에 나타나지 않도록 지정합니다.
기본적으로 REST API 문서가 포함된 웹 모듈은 /api/docs
자원에서 사용 가능한 병합된 OpenAPI 문서에 나타납니다. 웹 모듈이 OpenAPI 문서에
나타나지 않게 하려면 서버 구성에서 webModuleDoc 요소의 속성을
변경하십시오.
contextRoot 속성을 사용하여 숨기거나 표시할 웹 모듈을
식별하십시오. 그런 다음 enabled 속성을 false로
변경하여 OpenAPI 문서에서 웹 모듈을 숨기십시오. enabled 속성의
기본값은 true입니다. 다음 예제는 airlinesAdmin
모듈이 숨겨져 있는 동안 OpenAPI 문서에 나타나도록 airlines 모듈을 구성합니다.
<openapi>
<webModuleDoc contextRoot="/airlines" enabled="true" />
<webModuleDoc contextRoot="/airlinesAdmin" enabled="false" />
</openapi>
참고: 기타 Liberty
기능에 의해 제공되는 REST API 문서에는 enabled 속성이 지원되지
않습니다.
- 옵션: JAX-RS 어노테이션 스캐닝을 사용으로 설정하십시오.
기능 관리자에 jaxrs-2.0 기능을 추가하십시오. 서버에서
jaxrs-2.0 및 openapi-3.0 기능이 모두
사용 가능한 경우 서버 구성에서 스캐닝을 사용 안함으로 설정하지 않으면
어노테이션 스캐너는 서버에 배치되는 모든 웹 애플리케이션을 스캔합니다.
스캐너는 클래스 정의의 OpenAPI 3.0 어노테이션으로 어노테이션이 작성되고
@Path JAX-RS 어노테이션으로 어노테이션이 작성된 클래스를
거칩니다. OpenAPI 공용 엔드포인트(api/docs) 및 개인용
엔드포인트(ibm/api/docs)를 사용하여 생성된 OpenAPI
문서에 액세스할 수 있습니다.
- 특정 애플리케이션에 대한 써드파티 API 가시성을 허용하십시오. OpenAPI 어노테이션, 모델 및 프로그래밍 모델의 런타임 로딩을 사용하려면
특정 애플리케이션에 대한 써드파티 API 가시성을 사용으로 설정해야 합니다.
- classloader 요소의 apiTypeVisibility
속성을 써드파티 API 가시성으로 정의하십시오. server.xml파일의
classloader 요소에 third-party를 추가하십시오.
apiTypeVisibility에 third-party를
포함하도록 classloader를 지정하지 않으면, spec
및 ibm-api의 기본 정의를 사용합니다.
<application id="scholar" name="Scholar" type="ear" location="scholar.ear">
<classloader apiTypeVisibility="spec, ibm-api, third-party" commonLibraryRef="Alexandria" />
</application>
- 옵션: OpenAPI 문서의 유효성 검증을 사용으로 설정하십시오.
유효성 검증 기능은 기본적으로 사용 불가능합니다. 유효성 검증을 사용으로 설정하면
애플리케이션에서 제공하는 각 OpenAPI 문서가 openapi-3.0 기능으로
OpenAPI V3 스펙에 선언된 제한조건에 대해 유효성 검증됩니다. openapi-3.0이
올바르지 않은 OpenAPI 문서를 찾으면 이 기능은 위반된 각 제한조건에 대한 로그에
오류를 보고합니다. 올바르지 않은 문서는 api/docs 엔드포인트에서
리턴되는 집계된 OpenAPI 문서에서 제외됩니다. 유효성 검증을 사용하려면
server.xml 파일에서 validation 속성을
true로 설정하십시오.
<openapi validation="true"/>
- 애플리케이션을 배치하십시오.
- 브라우저에서 생성된 API 문서를 보십시오.
API가 공용인지 개인용인지 여부에 따라 다음 URL 중 하나를 사용하여 /api/docs 엔드포인트에서 생성된 API 문서를 찾을 수 있습니다.
- 비SSL 공용 API의 경우 http://Liberty_host:http_port/api/docs에서
문서를 보십시오.
- SSL 공용 API의 경우 https://Liberty_host:https_port/api/docs에서
문서를 보십시오.
- SSL 개인용 API의 경우
https://Liberty_host:https_port/ibm/api/docs에서
문서를 보십시오.
팁: 기본적으로 서버에는 두 개의 엔드포인트를 사용할 수 있습니다.
- GET http://Liberty_host:http_port/api/docs
- GET http://Liberty_host:http_port/api/explorer
server.xml 파일의
publicURL 속성을 사용하여 공용 엔드포인트의 URL을 사용자 정의할 수 있습니다.
다음 예제에서는
GET http://Liberty_host:http_port/myAPI/docs 및
http://Liberty_host:http_port/myAPI/explorer로 공용 REST API 문서를 사용할 수 있도록 하는
server.xml 파일의 구성을 보여줍니다.
<openapi publicURL="myAPI" />
OpenAPI 문서는 해당 Liberty
서버의 애플리케이션에서 생성되고 집계됩니다. 문서는 기본적으로 YAML 형식입니다.
Microsoft Internet Explorer 11에서
문서를 볼 때 형식이 올바르지 않은 YAML 문서를 리턴합니다. 이 문제를 해결하려면
Mozilla Firefox 또는
Google Chrome 브라우저와 같은
브라우저를 사용하십시오. http 요청에 application/json
값이 있는 Accept 헤더가 있으면 문서는 JSON 형식입니다.
팁: 컨텍스트 루트별로 OpenAPI 문서를 필터링할 수 있습니다. 공용
엔드포인트(api/docs) 및 개인용
엔드포인트(ibm/api/docs)는 모두 발견된 조회 매개변수를
필터링할 수 있는 root라는 조회 매개변수를 지원합니다. 예를 들어, GET
http://Liberty_host:http_port/api/docs?root=/myApp에
대한 호출은 myApp 컨텍스트 루트에 대한 문서만 있는 OpenAPI V3
문서를 검색합니다.
결과
OpenAPI 사용자 인터페이스는 /api/docs에서 집계된 정의를
렌더링하여 http://Liberty_host:http_port/api/explorer에서
인간 친화적인 UI를 표시합니다. SSL을 사용으로 설정하는 경우
https://Liberty_host:https_port/api/explorer에서
보호 UI에 액세스할 수 있습니다.
server.xml 파일의
openAPI 요소에서
enablePrivateURL 속성을 사용으로 설정하여 개인용 웹 모듈을
찾아볼 수 있습니다.
<openapi enablePrivateURL="true"/>
개인용 웹 모듈
브라우징이 사용 가능한 경우,
https://Liberty_host:https_port/ibm/api/explorer를
사용하여 공용 및 개인용 웹 모듈 모두에 대해 인간 친화적인 UI를 표시하십시오.
이 사용자 인터페이스에서 애플리케이션의 모든 RESTful 엔드포인트를 볼 수
있습니다. 또한 특정 애플리케이션에 초점을 지정하도록 표시된 엔드포인트를
필터링할 수 있습니다.