OpenAPI V3 编程接口

您可以使用以下编程接口来扩展 openapi-3.0 功能部件。请参阅 GitHub 上的 OpenAPI V3 样本应用程序来构建您自己的 OpenAPI 模型并生成文档。

应用程序编程接口 (API)
服务编程接口 (SPI)

已稳定的功能部件: OpenAPI V3 功能部件 openapi-3.0 和 openapi-3.1已稳定。您可继续使用这些功能部件。但是，战略替代方法是使用 MicroProfile OpenAPI 功能部件，例如 mpOpenAPI-3.0。

应用程序编程接口 (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()     
    };
}