Liberty 서버에서 REST API 문서 발견
![[18.0.0.1 and later]](../ng_v18001plus.gif)
프로시저
- 사용 가능한 REST API를 찾고자 하는 Liberty 서버의
server.xml 파일의 기능 관리자에 apiDiscovery-1.0 기능을 추가하십시오.
apiDiscovery-1.0 기능은 제품의 REST API 발견 번들을 사용으로 설정합니다. 또한 이 기능은 서버 구성이 restConnector-1.0 기능을 사용하는 경우 JMX 등의 Liberty REST 엔드포인트에서, 그리고 서버 구성이 collectiveController-1.0 기능을 사용하는 경우 집합체에서 문서를 표시합니다.
Liberty 집합체 제어기 서버에서 사용되는 apiDiscovery-1.0 기능은 제어기 및 apiDiscovery-1.0 기능이 사용되는 해당 멤버 서버에서 사용 가능한 REST API를 찾습니다.
jaxrs-2.0 등의 배치된 애플리케이션에 필요한 모든 기능이 서버 구성에 있는지 확인하십시오. 서버가 해당 HTTP 포트를 열 수 있도록 포트를 수정하십시오.
개인용 REST API 문서를 표시하려면, server.xml 파일에서 키 저장소 서비스 오브젝트 항목과 사용자 레지스트리 항목을 구성하십시오.
그러나 공용 REST API 문서만 표시하려면, HTTPS를 통해 문서에 액세스하고자 하는 경우에만 키 저장소 오브젝트 항목을 추가하십시오. HTTP를 통한 공용 문서 액세스에서는 키 저장소 오브젝트 항목이나 사용자 레지스트리 설정이 필요하지 않습니다.
다음 server.xml 파일에 apiDiscovery-1.0 기능이 있습니다.
<server> <featureManager> <feature>apiDiscovery-1.0</feature> </featureManager> <httpEndpoint id="defaultHttpEndpoint" host="*" httpPort="8010" httpsPort="8020"/> <keyStore id="defaultKeyStore" password="Liberty"/> <basicRegistry id="basic" realm="ibm/api"> <user name="bob" password="bobpwd" /> </basicRegistry> </server>
- Liberty REST 엔드포인트에서 Swagger 2.0 문서를 표시하십시오.
웹 애플리케이션에 API 발견 기능에서 올바르게 작동할 수 있도록 javax.ws.rs.core.Application 클래스의 인스턴스가 둘 이상 포함된 경우, 각 애플리케이션에서는 web.xml 파일에 정의된 url-mapping 또는 고유 javax.ws.rs.@ApplicationPath 값이 필요합니다.
apiDiscovery-1.0 기능을 사용으로 설정하여 어노테이션 스캔 중에 찾는 문서와 현재 문서를 병합하십시오. 제품은 웹 모듈에서 META-INF/stub/swagger.json 또는 META-INF/stub/swagger.yaml 파일을 검색합니다. 기능이 해당 파일을 찾으면 기능이 웹 모듈에 있는 JAX-RS 및 Swagger 어노테이션과 파일 컨텐츠가 모두 포함된 Swagger 문서를 생성합니다. 문서는 자동으로 JAX-RS 부분과 병합되므로 이 기능을 사용하여 비JAX-RS 서블릿을 문서화할 수 있습니다. 다음 두 가지 방법 중 하나로 API 문서 위치를 구성할 수 있습니다.
- SPI com.ibm.wsspi.rest.api.discovery.APIProvider 인터페이스의
getDocument 메소드를 사용하십시오.
getDocument 메소드는 확장기능에서 OSGi 번들을 사용으로 설정하여 전체 마스터 문서에 REST API 문서를 컨트리뷰션할 수 있습니다. 이 릴리스의 경우 지원되는 유일한 DocType은 DocType.Swagger_20_JSON 및 DocType.Swagger_20_YAML입니다. 이 인터페이스의 구현자는 직렬화된 JSON 또는 YAML 문서를 java.lang.String 값으로 리턴하거나 JSON 또는 YAML 파일 위치에 대한 파일 참조(접두부: file:///)를 전달할 수 있습니다.
- 배치된 웹 애플리케이션을 사용하십시오.
각 웹 모듈은 고유 REST API 문서를 컨트리뷰션할 수 있습니다. 엔터프라이즈 애플리케이션(EAR) 파일 내에 있는 여러 WAR 파일에는 서로 다른 Swagger 2.0 문서가 있습니다.
웹 모듈의 문서를 표시하는 가장 쉬운 방법은 swagger.json 또는 swagger.yaml 파일을 해당 META-INF 폴더에 포함하는 것입니다. 애플리케이션 배치 중에 API 발견 기능은 각 웹 모듈의 META-INF/swagger.json 값을 검색합니다.META-INF/swagger.json 값을 찾을 수 없는 경우에는 API 발견 기능이 META‐INF/swagger.yaml 값을 찾습니다.
웹 모듈의 REST API 문서를 표시하는 또 다른 방법은 server.xml 구성 파일에 있습니다. 각 웹 모듈의 webModuleDoc 요소를 상위 apiDiscovery 요소에 두십시오. 예:
<apiDiscovery> <webModuleDoc contextRoot="/30ExampleServletInEar" enabled="true" docURL="/swagger.json" /> <webModuleDoc contextRoot="/22ExampleServlet" enabled="false" /> <webModuleDoc contextRoot="/custom" enabled="true" docURL="http://petstore.swagger.io/v2/swagger.json" /> </apiDiscovery>
webModuleDoc 요소에는 표시할 문서가 있는 웹 모듈을 고유하게 식별하는 contextRoot 속성이 있어야 합니다.
선택적 속성 enabled는 웹 모듈의 API 발견을 토글합니다. 이 속성의 기본값은 true입니다.
docURL 속성은 웹 모듈의 문서를 찾는 위치를 지정합니다. docURL 값은 URL이 컨텍스트 루트에 대해 상대적이 되도록 슬래시(/)로 시작할 수 있습니다(예: /30ExampleServletInEar/swagger.json). 문서의 전체 위치를 식별하는 절대 URL의 경우에는 docURL 값이 http 또는 https로 시작합니다.
웹 애플리케이션이 swagger.json 또는 swagger.yaml 파일을 제공하지 않고 애플리케이션에 JAX-RS 어노테이션이 있는 자원이 포함된 경우에는 Swagger 문서를 자동으로 생성할 수 있습니다. 서버 구성에는 apiDiscovery-1.0 기능 및 jaxrs-1.1 또는 jaxrs-2.0 기능이 있어야 합니다. 예:
본 제품은 웹 애플리케이션의 모든 클래스에서 JAX-RS 및 Swagger 어노테이션을 스캔하여 @Path, @Api 및 @SwaggerDefinition 어노테이션이 있는 클래스를 검색합니다. 또한 본 제품은 웹 애플리케이션 배치 또는 시작 중에 해당 Swagger 문서를 자동으로 생성합니다.<featureManager> <feature>apiDiscovery-1.0</feature> <feature>jaxrs-1.1</feature> </featureManager>
어노테이션 스캔 중에 찾는 문서와 이전에 생성된 문서를 병합하기 위해 apiDiscovery-1.0을 사용할 수도 있습니다. 제품은 웹 모듈에서 META-INF/stub/swagger.json 또는 META-INF/stub/swagger.yaml 파일을 검색합니다. 기능이 해당 파일을 찾으면 기능이 웹 모듈에 있는 JAX-RS 및 Swagger 어노테이션과 파일의 컨텐츠가 모두 포함된 Swagger 문서를 생성합니다. 문서는 자동으로 JAX-RS 부분과 병합되므로 이 기능을 사용하여 비JAX-RS 서블릿을 문서화할 수 있습니다.
이 기술은 표시된 보안 정의와 같은 어노테이션 제한사항을 무시하는 데 사용할 수 있습니다. 예를 들어, META-INF/stub 내의 다음 swagger.json은 어노테이션이 이러한 정의를 참조할 수 있도록 합니다.
{ "swagger" : "2.0", "securityDefinitions" : { "petstore_auth" : { "type" : "oauth2", "authorizationUrl" : "http://petstore.swagger.io/api/oauth/dialog," "flow" : "implicit", "scopes" : { "write_pets" : "modify pets in your account", "read_pets" : "read your pets" } }, "api_key" : { "type" : "apiKey", "name" : "api_key", "in" : "header" } } }
- SPI com.ibm.wsspi.rest.api.discovery.APIProvider 인터페이스의
getDocument 메소드를 사용하십시오.
- API 문서를 발견하십시오.
API 문서의 위치를 구성한 후 다음과 같은 방법으로 발견할 수 있습니다.
- GET
https://host:https_port/ibm/api/docs 엔드포인트를 사용하십시오.
이 엔드포인트는 단일 문서로 병합된 사용 가능한 모든 Liberty REST API를 올바른 Swagger 2.0 문서에 제공합니다. 이는 API 관리 솔루션과 같이 사용 가능한 API 세트를 프로그래밍 방식으로 탐색할 이용자 애플리케이션에 유용합니다. 선택사항인 Accept 헤더를 application/yaml 값과 함께 포함하면 YAML 형식의 Swagger 2.0 문서가 제공됩니다. 이 엔드포인트에는 발견된 컨텍스트 루트를 필터링할 수 있는 다중 카디널리티 선택적 조회 매개변수 root가 있습니다. 예를 들어, GET https://host:https_port/ibm/api/docs?root=/myApp에 대한 호출은 myApp 컨텍스트 루트에 대한 문서만 있는 Swagger 2.0 문서를 검색합니다.
- GET
https://host:https_port/ibm/api/explorer 엔드포인트를
사용하십시오.
이 엔드포인트는 /ibm/api/docs URL에서 컨텐츠를 표시하는 렌더링된 흥미 있는 HTML 페이지를 제공합니다. 사용자가 REST API를 시작할 수 있도록, 이 페이지는 표준 온라인 샘플(http://petstore.swagger.io/)과 동일한 패턴을 따릅니다. 이 엔드포인트는 Liberty 서버에서 사용 가능한 REST API를 탐색하고 아마도 페이지에서 이를 시작하는 데 도움이 됩니다.
페이지에 있는 필터 입력 상자는 컨텍스트 루트의 쉼표로 구분된 목록이 컨텐츠를 필터링할 수 있게 합니다.
- 집합체
제어기의 경우 GET
https://host:https_port/ibm/api/collective/docs 엔드포인트를
사용하십시오.
집합체 제어기의 이 엔드포인트는 집합체 제어기 및 apiDiscovery-1.0 기능이 사용되는 해당 멤버에서 사용 가능하며 단일 문서로 병합된 REST API를 올바른 Swagger 2.0 문서에 제공합니다. 이는 API 관리 솔루션과 같이 사용 가능한 API 세트를 프로그래밍 방식으로 탐색할 이용자 애플리케이션에 유용합니다. 선택사항인 Accept 헤더를 application/yaml 값과 함께 포함하면 YAML 형식의 Swagger 2.0 문서가 제공됩니다.
이 엔드포인트에는 root라고 하는 하나의 다중 카디널리티, 선택적 조회 매개변수가 있습니다.
조회 매개변수 root는 발견된 컨텍스트 루트를 필터링할 수 있습니다. 예를 들어, GET https://host:https_port/ibm/api/collective/docs?root=/myApp에 대한 호출은 myApp 컨텍스트 루트에 대한 문서만 있는 Swagger 2.0 문서를 검색합니다.
17.0.0.1 이전 버전의 경우 이 엔드포인트에는 두 개의 다중 카디널리티 선택적 조회 매개변수인 root 및 serverID가 있습니다. 조회 매개변수 root는 이전과 동일합니다. 조회 매개변수 serverID는 Liberty 서버에서 사용 가능한 REST API를 필터링할 수 있습니다. serverID 형식은 hostName,userDir,serverName입니다. 예를 들어, GET https://host:https_port/ibm/api/collective/docs?serverID=samplehost.com:8020,/users/admin/wlp/usr,server1에 대한 호출은 지정된 serverID의 Liberty 서버에서 사용 가능한 REST API에 대한 문서만 있는 Swagger 2.0 문서를 검색합니다.
- 집합체 제어기의 경우
GET
https://host:https_port/ibm/api/collective/explorer 엔드포인트를
사용하십시오.
집합체 제어기의 이 엔드포인트는 /ibm/api/collective/docs URL에서 컨텐츠를 표시하는 렌더링된 흥미 있는 HTML 페이지를 제공합니다. 이 엔드포인트에서는 전체 집합체에서 사용 가능한 REST API를 탐색하여 페이지에서 시작할 수 있습니다. 페이지의 필터 입력 상자는 컨텍스트 루트의 쉼표로 구분된 목록 및 서버 ID가 컨텐츠를 필터링할 수 있게 합니다. 서버 ID 형식은 "hostName,userDir,serverName"입니다. 따옴표(")로 서버 ID를 묶어야 합니다. 시작해 보기 단추로 API를 테스트하려면 멤버 서버의 server.xml에서 CORS(Cross Origin Request Sharing)를 설정해야 합니다.
17.0.0.1 이전 버전의 경우 API /IBMJMXConnectorREST/mbeanCount를 제공하는 멤버 서버의 server.xml에 다음 예제와 같은 스니펫이 필요합니다.
<cors domain="/IBMJMXConnectorREST/mbeanCount" allowedOrigins="https://controller_hostname:https_port" allowedMethods="GET,POST,DELETE,PUT,PATCH,OPTIONS" allowedHeaders="Content-Type,api_key,Authorization" allowCredentials="true" />
CORS 설정에 대한 정보는 Liberty 서버에 CORS(Cross Origin Resource Sharing) 구성의 내용을 참조하십시오.
참고: CORS 요구사항은 Swagger UI의 집합체 버전에만 적용됩니다(https://host:https_port/ibm/api/collective/explorer). 공용 REST 문서를 표시하려면 다른 엔드포인트를 사용하십시오.
이전에 언급한 엔드포인트와는 달리, 이러한 엔드포인트에 액세스하기 위해 키 저장소 서비스 오브젝트 항목이나 사용자 레지스트리 설정이 필요하지 않습니다. 그러나 HTTPS를 통해 엔드포인트에 액세스하기 위해 키 저장소 서비스 오브젝트 항목을 설정할 수 있습니다.
기본적으로 집합체 제어기에는 4개의 엔드포인트를 사용할 수 있습니다.- GET http://host:http_port/api/docs
- GET http://host:http_port/api/explorer
- GET http://host:http_port/api/collective/docs
- GET http://host:http_port/api/collective/explorer
기본적으로 서버에는 두 개의 엔드포인트를 사용할 수 있습니다.- GET http://host:http_port/api/docs
- GET http://host:http_port/api/explorer
공용 엔드포인트의 URL을 server.xml의 publicURL 속성으로 변경할 수 있습니다. 예를 들어, server.xml에서 다음 구성을 설정하면 GET http://host:http_port/myAPI/docs 및 http://host:http_port/myAPI/explorer로 공용 REST API 문서를 사용할 수 있습니다.
<apiDiscovery publicURL="myAPI" />
기본적으로, JMX REST 커넥터 REST API 등의 내부 서버 엔드포인트를 제외한 배치된 웹 애플리케이션이 컨트리뷰션한 모든 REST API 엔드포인트가 공용 REST API 문서에 표시됩니다. 모듈에 의해 표시되는 REST API를 표시하지 않도록 웹 모듈에 대해 public="false" 속성을 설정할 수 있습니다. 예를 들어, server.xml에 다음 구성을 추가하면 웹 모듈에 의한 REST API가 공용 REST API 문서에 표시되지 않습니다.
<apiDiscovery publicURL="myAPI"> <webModuleDoc contextRoot="/22ExampleServlet" public="false" /> </apiDiscovery>
server.xml 파일의 swaggerDefinition 속성을 사용하여 /docs 엔드포인트에서 제공하는 Swagger 2.0 문서의 일부 필드를 겹쳐쓸 수 있습니다.
swaggerDefinition을 사용하여 겹쳐쓸 필드가 포함된 JSON 또는 YAML Swagger 스니펫을 지정할 수 있습니다. info, schemes, consumes, produces 및 externalDocs 필드를 겹쳐쓸 수 있습니다.
집합체 제어기의 경우에는 집합체 서비스 조회를 사용하여 전체 집합체의 사용 가능한 모든 공용 RESTful API(서비스)를 나열하십시오.
apiDiscovery-1.0 기능을 사용하면 ObjectName 값 WebSphere:feature=apiDiscovery,name=APIDiscovery를 지닌 관리 Bean(MBean)이 Liberty MBeanServer에서 등록됩니다. 이 MBean은 다음과 같은 속성을 제공합니다.
- DocumentationURL 속성은 /ibm/api/docs 엔드포인트의 전체 URL이며 원시 JSON 또는 YAML 문서를 표시합니다.
- ExplorerURL 속성은 /ibm/api/explorer 엔드포인트의 전체 URL이며 문서의 렌더링된 UI를 표시합니다.
이 MBean을 사용하여 REST API 발견이 사용으로 설정되는지 여부 및 클라이언트가 REST API 발견에 도달할 수 있는 위치에 대해 학습할 수 있습니다.
- GET
https://host:https_port/ibm/api/docs 엔드포인트를 사용하십시오.
예
REST API 발견에 대한 자세한 정보는 OpenAPI 인터페이스 및 WASdev 웹 사이트에서 찾을 수 있습니다.
시청: IBM MediaCenter의 IBM
WebSphere Application Server Liberty API 발견 비디오는 예제 및 데모
비디오에 대한 링크를 제공합니다. (V8.5.5.9)
하위 주제
Swagger 2.0 문서 필드 겹쳐쓰기
server.xml 파일의 swaggerDefinition 속성을 사용하여 /docs 및 /explorer 엔드포인트에서 제공하는 Swagger 2.0 문서의 일부 필드를 겹쳐쓸 수 있습니다.집합체에서 모든 공용 RESTful API 나열
집합체 서비스 조회를 사용하여 전체 집합체에서 모든 공용 RESTful API(서비스)에 대한 API 문서를 찾을 수 있습니다. 조회에서는 목록 형식의 문서를 제공합니다.- Liberty REST API 업데이트 구독
Liberty REST API 발견 기능은 이제 새 REST API, /ibm/api/docs/subscription을 노출하며, 이에 따라 사용자는 사용 가능하게 될 새 API 또는 제거될 이전 API 등의 REST API 업데이트 사항을 구독할 수 있습니다. 이는 특정 Liberty 인스턴스가 제공하는 엔드포인트의 변경사항에 대해 사용자가 즉각적으로 알림을 받고자 하는 경우에 유용합니다. - 집합체에서 Liberty REST API 업데이트 구독
집합체 제어기의 구독 API를 사용하면 특정 집합체 멤버 서버로부터 엔드포인트의 변경사항과 같은 변경사항, 제거된 API 또는 새 REST API에 대해 즉시 학습할 수 있습니다. - API를 IBM API Connect 안으로 푸시하기 위한 REST 엔드포인트
사내 구축 환경 및 클라우드 Liberty 사용자 모두의 중심 위치인 REST 엔드포인트를 사용하여 API를 시각화하고 호출하며 IBM® API Connect에 푸시할 수 있습니다.

파일 이름: twlp_api_discovery.html