[17.0.0.3 und höher]

OpenAPI-V3-Programmierschnittstellen

Sie können die folgenden Programmierschnittstellen verwenden, um das Feature openapi-3.0 zu erweitern. Sehen Sie sich die OpenAPI-V3-Beispielanwendung auf GitHub an, um Ihre eigenen OpenAPI-Modelle zu erstellen und die Dokumentation zu generieren.

Anwendungsprogrammierschnittstellen (APIs)

Sie können die Programmierschnittstellen io.swagger.oas.integration verwenden, um Parameter in Bezug auf die OpenAPI-V3-Verarbeitung in Liberty zu konfigurieren. Diese Parameter sind in den JAR-Dateien im Verzeichnis /wlp/dev/api/third-party enthalten.

OpenAPIConfiguration
Die Schnittstelle io.swagger.oas.integration.OpenAPIConfiguration ist ein Container für alle Konfigurationsparameter in der OpenAPI-V3-Verarbeitung. Mit dieser Schnittstelle können Sie ein vollständiges OpenAPI-Modell bereitstellen, Annotationsscannen inaktivieren oder konfigurieren und weitere Helper-Services bereitstellen. Diese Services beinhalten einen angepassten Reader und Scanner.
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
Die Schnittstelle io.swagger.oas.integration.OpenAPIConfigurationBuilder ist der Hauptservice, der die Anpassung der OpenAPI-V3-Verarbeitung in Liberty ermöglicht. Sie können die OpenAPIConfigurationBuilder-Schnittstelle verwenden, um frameworkunabhängige Umgebungsvariablen zu erhalten, die sie beim Erstellen eines neuen OpenAPIConfiguration-Objekts verarbeitet.
public interface OpenAPIConfigurationBuilder {
   OpenAPIConfiguration build(Map<String, Object> environment);
}

Der folgende Beispielcode verwendet OpenAPIConfigurationBuilder, um ein OpenAPI-Modell mit der OpenAPI-V3-Beispielanwendung zu erstellen.

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;
   }
}

Damit das Feature openapi-3.0 den OpenAPIConfigurationBuilder starten kann, muss das Anwendungsarchiv eine Datei META-INF/services/io.swagger.oas.integration.OpenAPIConfigurationBuilder enthalten. Diese Datei enthält den vollständig qualifizierten Namen der OpenAPIConfigurationBuilder-Schnittstellenimplementierung. In diesem Beispiel ist der Wert com.example.AirlinesAPIs. Weitere Informationen zum Format dieser Datei finden Sie in der Java™ SE-Dokumentation zu java.util.ServiceLoader.

OpenAPIReader
Die io.swagger.oas.integration.OpenAPIReader-Schnittstelle ermöglicht es einem Anwendungsentwickler, einen angepassten JAX-RS-Reader anstelle der Standardimplementierung des JAX-RS-Readers bereitzustellen. Wenn Sie den OpenAPIReader-Service aktivieren, können Sie anpassen, wie der Laufzeitserver Klassen und Ressourcen verarbeitet.
public interface OpenAPIReader {
    void setConfiguration(OpenAPIConfiguration openAPIConfiguration);
    OpenAPI read(Set<Class<?>> classes, Map<String, Object> resources);
}

Damit das Feature openapi-3.0 den angegebenen OpenAPIReader implementiert, muss das Anwendungsarchiv eine Datei META-INF/services/io.swagger.oas.integration.OpenAPIReader enthalten. Diese Datei enthält den vollständig qualifizierten Namen der OpenAPIReader-Schnittstellenimplementierung.

Sie können auch den vollständig qualifizierten Namen der Implementierungsklasse mit io.swagger.oas.integration.OpenAPIConfiguration.getReaderClass() angeben.

OpenAPIScanner
Sie können konfigurieren, welche Klassen und Ressourcen vom JAX-RS-Reader mit dem io.swagger.oas.integration.OpenAPIScanner verarbeitet werden. Wenn Sie diesen Service aktivieren, wird der Annotationscan von Liberty außer Kraft gesetzt.
public interface OpenAPIScanner {
    void setConfiguration(OpenAPIConfiguration openAPIConfiguration);
    Set<Class<?>> getClasses();
    Map<String, Object> getResources();
}

Ähnlich wie bei dem OpenAPIConfigurationBuilder und dem OpenAPIReader muss auch das Anwendungsarchiv eine Datei META-INF/service/io.swagger.oas.integration.OpenAPIScanner enthalten. Diese Datei enthält den vollständig qualifizierten Namen der OpenAPIScanner-Schnittstellenimplementierung.

Sie können auch den vollständig qualifizierten Namen der Implementierungsklasse mit io.swagger.oas.integration.OpenAPIConfiguration.getReaderClass() angeben.

Serviceprogrammierschnittstellen (SPIs)

Das Feature openapi-3.0 führt eine Schnittstelle für OSGi-Bundles ein, um OpenAPI-V3-Dokumentation für APIs bereitzustellen. SPI-Benutzer können OpenAPI-V3-Dokumentation für OSGi-Bundles generieren, die anwendungsbasierte Erweiterungen oder Produkterweiterungen sind. Sie finden diese SPIs im Verzeichnis /wlp/dev/spi/ibm. Wenn Sie Ihrer Dokumentation Beiträge hinzufügen möchten, registrieren Sie eine Implementierung der Schnittstelle com.ibm.wsspi.openapi.OASProvider im OSGi-Framework.

OASProviderConfig
OASProviderConfig ist eine Helper-Klasse mit Unterstützungsoptionen, die mit einem bestimmten OpenAPI-V3-Dokument verknüpft werden kann. Sie können OASProviderConfig verwenden, um die Sprache anzugeben, in der Ihre Dokumente geschrieben wurden.
Einschränkung: Es wird nur das erste vom OASProvider zurückgegebene Ergebnis verwendet, wenn openapi-3.0 die Dokumentation generiert. openapi-3.0 unterstützt keine OASProvider-Konfigurationen für mehrere Sprachen. Geben Sie Provider an, die nur ein einziges Ergebnis zurückgeben.
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
Die Schnittstelle OASProviderResult gibt ein einziges OpenAPI-V3-Dokument zurück, indem entweder das OpenAPI-Modell verwendet wird, oder es wird ein YAML- oder JSON-Text, der als Java-Zeichenfolge formatiert ist, verwendet. Die angehängte Konfiguration wird verwendet, um dem Dokument Metadaten bereitzustellen.
public interface OASProviderResult {
    OpenAPI getOpenAPI();
    String getDocument();
    OASProviderConfig getOASProviderConfig();
}
OASProvider
Diese Schnittstelle ist der Hauptservice, den SPI-Benutzer implementieren müssen, um ihrem OpenAPI-V3-Feature Dokumentation bereitzustellen. Wenn Sie Dokumentation beitragen möchten, müssen Sie einen OASProvider für jedes Kontextstammverzeichnis, das Sie dokumentieren möchten, registrieren.
public interface OASProvider {
    List<OASProviderResult> getResults();
    String getContextRoot();
    boolean isPublic()     
    };
}

Symbol das den Typ des Artikels anzeigt. Referenzartikel

Dateiname: rwlp_api_openapi_interfaces.html