Liberty 서버에서 REST API 문서 발견

API 검색 기능을 사용하여 사용 가능한 REST API를 찾아서 Liberty 서버의 REST API 문서를 검색할 수 있습니다. 사용 가능한 REST 엔드포인트를 호출하려면 Swagger 사용자 인터페이스를 사용하십시오.

프로시저

  1. 찾으려는 REST API가 사용 가능한 Liberty 서버의 server.xml 파일에 있는 기능 관리자에 apiDiscovery-1.0 기능을 추가하십시오.

    apiDiscovery-1.0 기능으로 제품의 REST API 발견 번들을 사용할 수 있습니다. 또한 이 기능은 JMX(서버 구성이 restConnector-1.0 기능을 사용하는 경우) 및 집합체(서버 구성이 collectiveController-1.0 기능을 사용하는 경우)와 같은 Liberty REST 엔드포인트에서 문서를 표시합니다.

    배치된 애플리케이션에 필요한 모든 기능이 서버 구성에 있는지 확인하십시오(예: servlet-3.0, jsp-2.2 등). 배치된 애플리케이션에 대해 포트 및 사용자 레지스트리 설정이 올바른지 확인하십시오.

    다음 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>
  2. Liberty REST 엔드포인트에 Swagger 2.0 문서를 표시하십시오.

    웹 애플리케이션에 API 발견 기능과 함께 올바르게 작동하는 두 개 이상의 javax.ws.rs.core.Application 클래스가 있는 경우, 각 애플리케이션에는 고유한 javax.ws.rs.@ApplicationPath 값이 필요하거나 web.xml 파일에서 정의된 URL 맵핑이 필요합니다.

    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_JSONDocType.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 구성 파일에 있습니다. 상위 apiDiscovery 요소에 각 웹 모듈의 webModuleDoc 요소를 두십시오. 예:

      <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 기능이 있어야 합니다. 예:
      <featureManager>
          <feature>apiDiscovery-1.0</feature>
          <feature>jaxrs-1.0</feature>
      </featureManager>
      본 제품은 웹 애플리케이션의 모든 클래스에서 JAX-RS 및 Swagger 어노테이션을 스캔하여 @Path, @Api@SwaggerDefinition 어노테이션이 있는 클래스를 검색합니다. 또한 본 제품은 웹 애플리케이션 배치 또는 시작 중에 해당 Swagger 문서를 자동으로 생성합니다.

      어노테이션 스캔 중에 찾는 문서와 이전에 생성된 문서를 병합하기 위해 apiDiscovery-1.0을 사용할 수도 있습니다. 본 제품은 웹 모듈에서 META-INF/stub/swagger.json 또는 META-INF/stub/swagger.yaml 파일을 검색합니다. 기능이 해당 파일을 찾으면 기능이 웹 모듈에 있는 JAX-RS 및 Swagger 어노테이션과 파일의 컨텐츠가 모두 포함된 Swagger 문서를 생성합니다. 문서는 자동으로 JAX-RS 부분과 병합되므로 이 기능을 사용하여 비JAX-RS 서블릿을 문서화할 수 있습니다.

      이 기술은 보안 정의 노출과 같은 어노테이션 제한사항을 무시하는 데 사용할 수 있습니다. 예를 들어, 다음 swagger.json, inside META-INF/stub는 어노테이션이 해당 정의를 참조하도록 허용합니다.

      {
        "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"
          }
        }
      }
  3. 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 페이지를 제공합니다. 이 페이지는 표준 온라인 샘플(http://petstore.swagger.io/)과 동일한 패턴을 따르므로 사용자가 REST API를 호출할 수 있습니다. 이 엔드포인트에서는 Liberty 서버에서 사용 가능한 REST API를 탐색하여 페이지에서 호출할 수 있습니다. 페이지에 있는 필터 입력 상자는 컨텍스트 루트의 쉼표로 구분된 목록이 컨텐츠를 필터링할 수 있게 합니다. 이 필터링은 root 조회 매개변수와 같이 작동합니다.필요한 입력 값을 제공하여 API를 테스트 구동한 후 시도하기를 클릭할 수 있습니다.

    apiDiscovery-1.0 기능을 사용으로 설정하면 ObjectNameWebSphere: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 발견에 도달할 수 있는 위치에 대해 학습할 수 있습니다.


주제의 유형을 표시하는 아이콘 태스크 주제



시간소인 아이콘 마지막 업데이트 날짜: Tuesday, 6 December 2016
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=cord&product=was-nd-mp&topic=twlp_api_discovery
파일 이름: twlp_api_discovery.html