[17.0.0.3 and later]

OpenAPI V3 프로그래밍 인터페이스

다음 프로그래밍 인터페이스를 사용하여 openapi-3.0 기능을 확장할 수 있습니다. 사용자 고유의 OpenAPI 모델을 빌드하고 문서를 생성하려면 GitHub의 OpenAPI V3 샘플 애플리케이션을 참조하십시오.

API(Application Programming Interface)

io.swagger.oas.integration 프로그래밍 인터페이스를 사용하여 Liberty에서 OpenAPI V3 처리와 관련된 매개변수를 구성할 수 있습니다 이러한 매개변수는 /wlp/dev/api/third-party 디렉토리의 JAR 파일에 있습니다.

OpenAPIConfiguration
io.swagger.oas.integration.OpenAPIConfiguration 인터페이스는 OpenAPI V3 처리에서 모든 구성 매개변수의 컨테이너입니다. 이 인터페이스를 사용하면 완전한 OpenAPI 모델을 제공하고, 어노테이션 스캐닝을 구성하거나 사용 안함으로 설정하고, 다른 헬퍼 서비스를 제공할 수 있습니다. 이러한 서비스에는 사용자 정의 리더 및 스캐너가 포함됩니다.
public interface OpenAPIConfiguration {
   Set<String> getResourcePackages();
   Set<String> getResourceClasses();
   String getReaderClass();
   String getScannerClass();
   Collection<String> getIgnoredRoutes();
   OpenAPI getOpenAPI();
   Map<String, Object> getUserDefinedOptions();
   Boolean isReadAllResources();
   Boolean isScanningDisabled();
}
OpenAPIConfigurationBuilder
io.swagger.oas.integration.OpenAPIConfigurationBuilder 인터페이스는 Liberty에서 OpenAPI V3 처리의 사용자 정의를 가능하게 하는 기본 서비스입니다. OpenAPIConfigurationBuilder를 사용하면 새로운 OpenAPIConfiguration 오브젝트를 빌드할 때 처리되는 프레임워크 종속 환경 변수를 수신할 수 있습니다.
public interface OpenAPIConfigurationBuilder {
   OpenAPIConfiguration build(Map<String, Object> environment);
}

다음 예제 코드는 OpenAPIConfigurationBuilder를 사용하여 OpenAPI V3 샘플 애플리케이션으로 OpenAPI 모델을 빌드합니다.

package com.example;

public final class AirlinesAPIs implements OpenAPIConfigurationBuilder {
   private OpenAPIConfiguration configuration = new OpenAPIConfiguration() {
      @Override
      public Boolean isScanningDisabled() {
         return Boolean.FALSE;
      }
      @Override
      public Boolean isReadAllResources() {
         return Boolean.TRUE;
      }
      @Override
      public Map<String, Object> getUserDefinedOptions() {
         return null;
      }
      @Override
      public String getScannerClass() {
         return "com.example.OpenAPIScannerImpl";
      }
      @Override
      public Set<String> getResourcePackages() {
         return null;
      }
      @Override
      public Set<String> getResourceClasses() {
         return null;
      }
      @Override
      public String getReaderClass() {
         return "com.example.OpenAPIReaderImpl";
      }
      @Override
      public OpenAPI getOpenAPI() {
         OpenAPI oai = new OpenAPI().info(new Info().title("Airlines").version("1.0.0")).paths(new Paths()
                 .addPathItem("/airlines", new PathItem().get(new Operation()
                     .description("Get the list of available airlines").responses(
                        new ApiResponses().addApiResponse("200", new ApiResponse().description("successful")
                            .content(new Content().addMediaType("application/json", new MediaType()
                                .schema(new Schema().$ref("#/components/schemas/Airlines")))))))));

         return oai;
      }
      @Override
      public Collection<String> getIgnoredRoutes() {
          return null;
      }
   };
   @Override
   public OpenAPIConfiguration build(Map<String, Object> environment) {
      return configuration;
   }
}

OpenAPIConfigurationBuilder를 시작하는 데 openapi-3.0 기능을 사용하려면 애플리케이션 아카이브에 META-INF/services/io.swagger.oas.integration.OpenAPIConfigurationBuilder 파일이 있어야 합니다. 이 파일의 컨텐츠는 OpenAPI ConfigurationBuilder 인터페이스 구현의 완전한 이름입니다. 이 예제의 경우, 값은 com.example.AirlinesAPIs입니다. 이 파일의 형식에 대한 자세한 정보는 java.util.ServiceLoader의 Java™ SE 문서를 참조하십시오.

OpenAPIReader
io.swagger.oas.integration.OpenAPIReader 인터페이스를 사용하면 애플리케이션 개발자가 JAX-RS 리더의 기본 구현 대신 사용자 정의 JAX-RS 리더를 제공할 수 있습니다. OpenAPIReader 서비스를 사용으로 설정하면 런타임 서버가 클래스 및 자원을 처리하는 방법을 사용자 정의할 수 있습니다.
public interface OpenAPIReader {
    void setConfiguration(OpenAPIConfiguration openAPIConfiguration);
    OpenAPI read(Set<Class<?>> classes, Map<String, Object> resources);
}

지정된 OpenAPIReader를 구현하는 데 openapi-3.0 기능을 사용하려면 애플리케이션 아카이브에 META-INF/services/io.swagger.oas.integration.OpenAPIReader 파일이 있어야 합니다. 이 파일에는 OpenAPIReader 인터페이스 구현의 완전한 이름이 포함되어 있습니다.

io.swagger.oas.integration.OpenAPIConfiguration.getReaderClass()를 사용하여 구현 클래스의 완전한 이름을 지정할 수도 있습니다.

OpenAPIScanner
io.swagger.oas.integration.OpenAPIScanner를 사용하여 JAX-RS 리더가 처리하는 클래스 및 자원을 구성할 수 있습니다. 이 서비스를 사용하면 Liberty에 의한 어노테이션 스캐닝이 대체됩니다.
public interface OpenAPIScanner {
    void setConfiguration(OpenAPIConfiguration openAPIConfiguration);
    Set<Class<?>> getClasses();
    Map<String, Object> getResources();
}

OpenAPIConfigurationBuilderOpenAPIReader와 마찬가지로, 애플리케이션 아카이브에는 META-INF/service/io.swagger.oas.integration.OpenAPIScanner 파일이 포함되어야 합니다. 이 파일에는 OpenAPIScanner 인터페이스 구현의 완전한 이름이 포함되어 있습니다.

io.swagger.oas.integration.OpenAPIConfiguration.getReaderClass()를 사용하여 구현 클래스의 완전한 이름을 지정할 수도 있습니다.

SPI(Service Programming Interface)

openapi-3.0 기능은 API용 OpenAPI V3 문서를 제공하기 위한 OSGi 번들용 인터페이스를 도입합니다. SPI 사용자는 애플리케이션 기반 또는 제품 확장인 OSGi 번들용 OpenAPI V3 문서를 생성할 수 있습니다. 이러한 SPI는 /wlp/dev/spi/ibm 디렉토리에서 찾을 수 있습니다. 문서를 컨트리뷰션하려면 com.ibm.wsspi.openapi.OASProvider 인터페이스의 구현을 OSGi 프레임워크에 등록하십시오.

OASProviderConfig
OASProviderConfig는 특정 OpenAPI V3 문서에 링크할 수 있는 지원 옵션의 헬퍼 클래스입니다. OASProviderConfig를 사용하여 문서가 작성된 언어를 지정할 수 있습니다.
제한사항: openapi-3.0이 문서를 생성할 때 OASProvider에서 리턴되는 첫 번째 결과만 사용됩니다. openapi-3.0은 여러 언어에 대한 OASProvider 구성을 지원하지 않습니다. 하나의 결과만 리턴하는 제공자를 지정하십시오.
public final class OASProviderConfig {
    private String language;

    public String getLanguage() {
        return this.language;
    }

    public void setLanguage(String language) {
        this.language = language;
    }

    @Override
    public boolean equals(Object o) {
        if (o == null || getClass() != o.getClass()) {
                                    return false;
        }
        OASProviderConfig config = (OASProviderConfig) o;
        return Objects.equals(this.language, config.language);
    }

    @Override
    public int hashCode() {
        return Objects.hash(this.language);
    }

    public static OASProviderConfig defaultConfig() {
        return new OASProviderConfig();
    }
}
OASProviderResult
OASProviderResult 인터페이스는 OpenAPI 모델이나, Java String으로 형식화된 YAML 또는 JSON 텍스트 중 하나를 사용하여 단일 OpenAPI V3 문서를 리턴합니다. 여기에는 문서에 대한 메타데이터를 제공하기 위해 첨부된 구성이 있습니다.
public interface OASProviderResult {
    OpenAPI getOpenAPI();
    String getDocument();
    OASProviderConfig getOASProviderConfig();
}
OASProvider
이 인터페이스는 OpenAPI V3 기능에 대한 문서를 컨트리뷰션하기 위해 SPI 사용자가 구현해야 할 기본 서비스입니다. 문서를 컨트리뷰션하려면 문서화하려는 각 컨텍스트 루트에 대해 하나의 OASProvider를 등록해야 합니다.
public interface OASProvider {
    List<OASProviderResult> getResults();
    String getContextRoot();
    boolean isPublic()     
    };
}

주제의 유형을 표시하는 아이콘 참조 주제

파일 이름: rwlp_api_openapi_interfaces.html