Interfejsy programistyczne OpenAPI V3

Aby rozszerzyć składnik openapi-3.0 , można użyć następujących interfejsów programistycznych. Zapoznaj się z przykładową aplikacją OpenAPI V3 w serwisie GitHub , aby zbudować własne modele OpenAPI i wygenerować dokumentację.

[ 21.0.0.12 i nowsze]Stabilizowane funkcje: Funkcje OpenAPI V3 , openapi-3.0 i openapi-3.1, są stabilne. Można nadal korzystać z funkcji. Strategiczną alternatywą jest jednak użycie opcji MicroProfile OpenAPI, takiej jak mpOpenAPI-3.0.

Aplikacyjne interfejsy programistyczne (API)

Do konfigurowania parametrów powiązanych z przetwarzaniem OpenAPI V3 w Libertymożna użyć interfejsów programistycznych produktu io.swagger.oas.integration . Te parametry znajdują się w plikach JAR w katalogu /wlp/dev/api/third-party .

Konfiguracja OpenAPIConfiguration
Interfejs io.swagger.oas.integration.OpenAPIConfiguration jest kontenerem dla wszystkich parametrów konfiguracyjnych w przetwarzaniu OpenAPI V3 . Za pomocą tego interfejsu można udostępnić pełny model OpenAPI, wyłączyć lub skonfigurować skanowanie adnotacji, a także udostępnić inne usługi pomocnicze. Usługi te obejmują niestandardowy czytnik i skaner.

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
Interfejs io.swagger.oas.integration.OpenAPIConfigurationBuilder jest główną usługą, która umożliwia dostosowanie przetwarzania OpenAPI V3 w Liberty. Za pomocą OpenAPIConfigurationBuilder można odbierać zmienne środowiskowe zależne od środowiska, które przetwarza, gdy buduje nowy obiekt OpenAPIConfiguration.

public interface OpenAPIConfigurationBuilder {
   OpenAPIConfiguration build(Map<String, Object> environment);
}

Poniższy przykładowy kod używa produktu OpenAPIConfigurationBuilder do zbudowania modelu OpenAPI za pomocą przykładowej aplikacji OpenAPI V3 .


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

Aby składnik openapi-3.0 uruchamiał program OpenAPIConfigurationBuilder, archiwum aplikacji musi mieć plik META-INF/services/io.swagger.oas.integration.OpenAPIConfigurationBuilder . Treść tego pliku jest pełną nazwą implementacji interfejsu OpenAPIConfigurationBuilder. W tym przykładzie wartością jest com.example.AirlinesAPIs. Więcej informacji na temat formatu tego pliku można znaleźć w dokumentacji języka Java™ SE w serwisie java.util.ServiceLoader.

OpenAPIReader
Interfejs io.swagger.oas.integration.OpenAPIReader umożliwia programiście aplikacji udostępnianie niestandardowego czytnika JAX-RS zamiast domyślnej implementacji czytnika JAX-RS. Po włączeniu usługi OpenAPIReader można dostosować sposób przetwarzania klas i zasobów przez serwer środowiska wykonawczego.
public interface OpenAPIReader {
    void setConfiguration(OpenAPIConfiguration openAPIConfiguration);
    OpenAPI read(Set<Class<?>> classes, Map<String, Object> resources);
}

Aby składnik openapi-3.0 implementował określony produkt OpenAPIReader, archiwum aplikacji musi mieć plik META-INF/services/io.swagger.oas.integration.OpenAPIReader . Ten plik zawiera pełną nazwę implementacji interfejsu OpenAPIReader.

Można również określić pełną nazwę klasy implementacji za pomocą programu io.swagger.oas.integration.OpenAPIConfiguration.getReaderClass().

OpenAPIScanner
Użytkownik może skonfigurować, które klasy i zasoby są przetwarzane przez czytnik JAX-RS przy użyciu produktu io.swagger.oas.integration.OpenAPIScanner. Włączenie tej usługi nadpisuje skanowanie adnotacji przez Liberty.
public interface OpenAPIScanner {
    void setConfiguration(OpenAPIConfiguration openAPIConfiguration);
    Set<Class<?>> getClasses();
    Map<String, Object> getResources();
}

Podobnie, jak w przypadku produktów OpenAPIConfigurationBuilder i OpenAPIReader, archiwum aplikacji musi zawierać plik META-INF/service/io.swagger.oas.integration.OpenAPIScanner . Ten plik zawiera pełną nazwę implementacji interfejsu OpenAPIScanner.

Można również określić pełną nazwę klasy implementacji za pomocą programu io.swagger.oas.integration.OpenAPIConfiguration.getReaderClass().

Interfejsy programistyczne (Service Programming Interface-SPI)

Opcja openapi-3.0 wprowadza interfejs dla pakunków OSGi w celu udostępnienia dokumentacji OpenAPI V3 dla interfejsów API. Użytkownicy interfejsu SPI mogą generować dokumentację OpenAPI V3 dla pakunków OSGi, które są oparte na aplikacji lub rozszerzeniach produktów. Te SPI można znaleźć w katalogu /wlp/dev/spi/ibm . Aby wnosić dokumentację, zarejestruj implementację interfejsu com.ibm.wsspi.openapi.OASProvider w środowisku OSGi.

Konfiguracja_oASProviderConfig
OASProviderConfig to klasa pomocnicza opcji obsługi, która może być powiązana z konkretnym dokumentem OpenAPI V3 . Za pomocą programu OASProviderConfig można określić język, w którym zapisywane są dokumenty.
Ograniczenie: Po wygenerowaniu dokumentacji przez program openapi-3.0 używany jest tylko pierwszy wynik zwracany przez produkt OASProvider . Produkt openapi-3.0 nie obsługuje konfiguracji produktu OASProvider dla wielu języków. Określ dostawców, którzy zwracają tylko jeden wynik.
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();
    }
}
Wynik dostawcy OASProviderResult
Interfejs OASProviderResult zwraca pojedynczy dokument OpenAPI V3 przy użyciu modelu OpenAPI albo tekstu YAML lub JSON sformatowanego jako łańcuch Java. Ma ona przyłączoną konfigurację, która udostępnia metadane dotyczące dokumentu.
public interface OASProviderResult {
    OpenAPI getOpenAPI();
    String getDocument();
    OASProviderConfig getOASProviderConfig();
}
Dostawca OASProvider
Ten interfejs jest główną usługą, którą użytkownicy interfejsu SPI muszą implementować w celu wnoszenia dokumentacji do ich funkcji OpenAPI V3 . Aby wnieść dokumentację, należy zarejestrować jeden OASProvider dla każdego kontekstowego katalogu głównego, który ma zostać udokumentowany.
public interface OASProvider {
    List<OASProviderResult> getResults();
    String getContextRoot();
    boolean isPublic()     
    };
}