![[17.0.0.3 and later]](../ng_v17003plus.gif)
OpenAPI V3 编程接口
应用程序编程接口 (API)
您可以使用 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; } }
要使 openapi-3.0 功能部件启动 OpenAPIConfigurationBuilder,应用程序归档必须具有 META-INF/services/io.swagger.oas.integration.OpenAPIConfigurationBuilder 文件。此文件的内容是 OpenAPIConfigurationBuilder 接口实现的标准名称。对于此示例,该值为 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); }
要使 openapi-3.0 功能部件实现指定的 OpenAPIReader,应用程序归档必须具有 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)
openapi-3.0 功能部件为 OSGi 捆绑软件引入了一个接口,用于提供 API 的 OpenAPI V3 文档。SPI 用户可以生成基于应用程序或作为产品扩展的 OSGi 捆绑软件的 OpenAPI V3 文档。您可以在 /wlp/dev/spi/ibm 目录中找到这些 SPI。要添加您的文档,请将 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 字符串的 YAML 或
JSON 文本来返回单个 OpenAPI V3 文档。它具有用于提供有关文档的元数据的附加配置。
public interface OASProviderResult { OpenAPI getOpenAPI(); String getDocument(); OASProviderConfig getOASProviderConfig(); }
- OASProvider
- 此接口是 SPI 用户为了将文档添加到其 OpenAPI V3 功能部件而必须实现的主服务。要添加文档,您必须针对每个想要记录的上下文根注册一个 OASProvider。
public interface OASProvider { List<OASProviderResult> getResults(); String getContextRoot(); boolean isPublic() }; }