![[17.0.0.3 and later]](../ng_v17003plus.gif)
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(); }
OpenAPIConfigurationBuilder 및 OpenAPIReader와 마찬가지로, 애플리케이션 아카이브에는 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() }; }