[17.0.0.3 and later]

OpenAPI를 사용한 REST API 문서 생성

OpenAPI 스펙을 지원하는 openapi-3.0 기능을 사용하여 REST API 문서를 생성할 수 있습니다. REST API를 문서화하고 공용 및 개인용 API를 지정한 후 어노테이션 스캐닝을 사용하도록 선택하고 웹 애플리케이션을 Liberty 서버에 배치하십시오. 그런 다음 인간 친화적인 사용자 인터페이스를 사용하는 브라우저에서 openapi-3.0에 의해 생성되는 API 문서를 볼 수 있습니다.

시작하기 전에

OpenAPI V3 스펙에 대해 학습하십시오. YAML 또는 JSON 파일을 사용하여 애플리케이션의 RESTful API를 문서화합니다.

[18.0.0.1 and later]중요사항:

MicroProfile OpenAPI 스펙 버전 1.0에서 사용 가능한 Java 인터페이스 및 프로그래밍 모델을 사용할 수 있습니다. mpOpenAPI-1.0 기능은 MicroProfile OpenAPI 스펙을 구현합니다.

mpOpenAPI-1.0 기능에 대한 자세한 정보는 MicroProfile OpenAPI를 사용한 REST API 문서 생성의 내용을 참조하십시오.

이 태스크 정보

다음 샘플 애플리케이션을 사용하여 이러한 기능(예: 새 사용자 인터페이스, 어노테이션 및 프로그래밍 인터페이스)을 탐색할 수 있습니다.

프로시저

  1. OpenAPI 문서를 빌드하십시오.

    여러 가지 방법으로 OpenAPIs를 문서화하고 빌드할 수 있습니다.

    • Java 코드로 OpenAPI 어노테이션을 지정하여 애플리케이션을 기능 보강하고 문서화하십시오.
    • 텍스트 편집기를 사용하여 API를 OpenAPI 태그로 문서화한 다음 완료된 openapi.yaml, openapi.yml 또는 openapi.json 파일을 애플리케이션의 META-INF 디렉토리에 배치하십시오.
    • 애플리케이션 내에서 OpenAPI 모델을 빌드하려면 io.swagger.oas.integration.OpenAPIConfigurationBuilder 프로그래밍 인터페이스를 사용하십시오. 이 인터페이스와 OpenAPI V3용 기타 관련 프로그래밍 인터페이스는 /wlp/dev/api/third-party 디렉토리의 JAR 파일에서 찾을 수 있습니다. OpenAPIConfigurationBuilder를 시작하는 데 openapi-3.0 기능을 사용하려면 애플리케이션 아카이브에 META-INF/services/io.swagger.oas.integration.OpenAPIConfigurationBuilder 파일이 있어야 합니다. 이 파일의 컨텐츠는 OpenAPIConfigurationBuilder의 완전한 이름입니다.

      사용 가능한 프로그래밍 인터페이스, 기능 설명 및 사용 예제에 대한 자세한 정보는 OpenAPI V3 프로그래밍 인터페이스의 내용을 참조하십시오.

  2. Liberty 서버 구성에서 openapi-3.0 기능을 사용으로 설정하십시오.
    1. 기능 관리자에 openapi-3.0 기능을 추가하십시오.
      <server>
         <featureManager>
            <feature>openapi-3.0</feature>
         </featureManager>
      </server>
    2. 옵션: OpenAPI 애플리케이션을 개인용으로 지정하십시오.

      기본적으로 OpenAPI 문서는 공용입니다. 모든 사용자는 종종 인증없이 공용 API에 액세스할 수 있습니다. 공용 API는 /api/docs 자원에 문서화되어 있습니다.

      API가 개인용으로 유지되도록 지정할 수 있습니다. 관리용 API는 일반적으로 개인용으로 유지됩니다. 보호용 비밀번호를 사용하는 개인용 API는 /ibm/api/docs 자원에 문서화되어 있습니다. 이 자원은 모든 개인용 API 및 모든 공용 API를 문서화합니다.

      다음 두 가지 방법으로 웹 애플리케이션에 대한 개인용 API를 지정할 수 있습니다.

      • public속성이 false로 설정된 서버 구성에서 webModuleDoc를 사용하십시오.
        1. openapi 요소를 추가하고 해당 enablePrivateURL 부울 속성을 true로 설정하십시오.
        2. 각 웹 애플리케이션에 대한 webModuleDoc 하위 요소를 추가하고 공용 API의 경우 public 부울 속성을 true로 설정하고 개인용 API의 경우 false로 설정합니다.

        다음 예제는 airlines 애플리케이션 OpenAPI를 표시하고 airlinesAdmin 애플리케이션 OpenAPI의 노출을 사용 안함으로 설정합니다.

        <openapi enablePrivateURL="true">
          <webModuleDoc contextRoot="/airlines" public="true" />
          <webModuleDoc contextRoot="/airlinesAdmin" public="false" />
        </openapi>

        기본적으로 webModuleDocpublic 속성은 true로 설정됩니다. 이 구성은 개인용으로 유지하려는 애플리케이션을 사용 안함으로 설정하는 경우에만 필요합니다.

      • API 설명의 벤더 확장 키워드를 사용하여 API를 개인용으로 지정하십시오.
        1. 서버 구성에 openapi 요소를 추가하고 해당 enablePrivateURL 부울 속성을 true로 설정하십시오.
        2. API 설명 문서 META-INF/openapi.yaml 파일 또는 지원되는 다른 형식의 파일에 x-ibm-private: true 키워드 및 값을 넣으십시오. 이 값은 API의 기본 가시성을 대체하며 이 값을 webModuleDoc 항목으로 대체할 수 있습니다.
    3. 옵션: 애플리케이션이 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 속성이 지원되지 않습니다.
  3. 옵션: JAX-RS 어노테이션 스캐닝을 사용으로 설정하십시오.

    기능 관리자에 jaxrs-2.0 기능을 추가하십시오. 서버에서 jaxrs-2.0openapi-3.0 기능이 모두 사용 가능한 경우 서버 구성에서 스캐닝을 사용 안함으로 설정하지 않으면 어노테이션 스캐너는 서버에 배치되는 모든 웹 애플리케이션을 스캔합니다. 스캐너는 클래스 정의의 OpenAPI 3.0 어노테이션으로 어노테이션이 작성되고 @Path JAX-RS 어노테이션으로 어노테이션이 작성된 클래스를 거칩니다. OpenAPI 공용 엔드포인트(api/docs) 및 개인용 엔드포인트(ibm/api/docs)를 사용하여 생성된 OpenAPI 문서에 액세스할 수 있습니다.

  4. 특정 애플리케이션에 대한 써드파티 API 가시성을 허용하십시오. OpenAPI 어노테이션, 모델 및 프로그래밍 모델의 런타임 로딩을 사용하려면 특정 애플리케이션에 대한 써드파티 API 가시성을 사용으로 설정해야 합니다.
    1. classloader 요소의 apiTypeVisibility 속성을 써드파티 API 가시성으로 정의하십시오. server.xml파일의 classloader 요소에 third-party를 추가하십시오.

      apiTypeVisibilitythird-party를 포함하도록 classloader를 지정하지 않으면, specibm-api의 기본 정의를 사용합니다.

      <application id="scholar" name="Scholar" type="ear" location="scholar.ear">
        <classloader apiTypeVisibility="spec, ibm-api, third-party" commonLibraryRef="Alexandria" />
      </application>
  5. 옵션: OpenAPI 문서의 유효성 검증을 사용으로 설정하십시오.

    유효성 검증 기능은 기본적으로 사용 불가능합니다. 유효성 검증을 사용으로 설정하면 애플리케이션에서 제공하는 각 OpenAPI 문서가 openapi-3.0 기능으로 OpenAPI V3 스펙에 선언된 제한조건에 대해 유효성 검증됩니다. openapi-3.0이 올바르지 않은 OpenAPI 문서를 찾으면 이 기능은 위반된 각 제한조건에 대한 로그에 오류를 보고합니다. 올바르지 않은 문서는 api/docs 엔드포인트에서 리턴되는 집계된 OpenAPI 문서에서 제외됩니다. 유효성 검증을 사용하려면 server.xml 파일에서 validation 속성을 true로 설정하십시오.

    <openapi validation="true"/>
  6. 애플리케이션을 배치하십시오.
  7. 브라우저에서 생성된 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에서 문서를 보십시오.
    [17.0.0.4 and later]팁: 기본적으로 서버에는 두 개의 엔드포인트를 사용할 수 있습니다.
    • 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 엔드포인트를 볼 수 있습니다. 또한 특정 애플리케이션에 초점을 지정하도록 표시된 엔드포인트를 필터링할 수 있습니다.


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

파일 이름: twlp_api_openapi.html