![[17.0.0.3 und höher]](../ng_v17003plus.gif)
OpenAPI-V3-Programmierschnittstellen
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() }; }