Interfaces de programmation OpenAPI V3

Vous pouvez utiliser les interfaces de programmation suivantes pour étendre la fonction openapi-3.0. Utilisez l'exemple d'application OpenAPI V3 sur GitHub pour générer vos propres modèles OpenAPI et créer une documentation.

Fonctions stabilisées: les fonctions OpenAPI V3 , openapi-3.0 et openapi-3.1, sont stabilisées. Vous pouvez continuer de les utiliser. Toutefois, l'alternative stratégique consiste à utiliser une fonction MicroProfile OpenAPI telle que mpOpenAPI-3.0.

Interfaces de programmation d'application (API)

Vous pouvez utiliser les interfaces de programmation io.swagger.oas.integration pour configurer des paramètres liés au traitement OpenAPI V3 dans Liberty. Ces paramètres se trouvent dans les fichiers JAR du répertoire /wlp/dev/api/third-party.

OpenAPIConfiguration
L'interface io.swagger.oas.integration.OpenAPIConfiguration contient tous les paramètres de configuration utilisés dans le traitement de OpenAPI V3. Avec cette interface, vous pouvez fournir un modèle OpenAPI complet, désactiver ou configurer l'analyse des annotations et fournir d'autres services auxiliaires. Les services suivants incluent un lecteur et un scanner personnalisés.

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
L'interface io.swagger.oas.integration.OpenAPIConfigurationBuilder est le service principal qui active la personnalisation du traitement de OpenAPI V3 dans Liberty. Vous pouvez utiliser l'interface OpenAPIConfigurationBuilder pour recevoir des variables d'environnement dépendantes de l'infrastructure qu'elle traite lorsqu'elle génère un nouvel objet OpenAPIConfiguration.

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

L'exemple de code suivant utilise l'interface OpenAPIConfigurationBuilder pour générer un modèle OpenAPI avec l'exemple d'application 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;
   }
}

Pour que la fonction openapi-3.0 démarre l'interface OpenAPIConfigurationBuilder, l'archive d'application doit contenir un fichier META-INF/services/io.swagger.oas.integration.OpenAPIConfigurationBuilder. Le contenu de ce fichier est le nom complet d'implémentation de l'interface OpenAPIConfigurationBuilder. Dans cet exemple, la valeur est com.example.AirlinesAPIs. Pour plus d'informations sur le format de ce fichier, voir la documentation Java™ SE sur java.util.ServiceLoader.

OpenAPIReader
L'interface io.swagger.oas.integration.OpenAPIReader permet à un développeur d'application de fournir un lecteur JAX-RS personnalisé de l'implémentation par défaut du lecteur JAX-RS. Lorsque vous activez le service OpenAPIReader, vous pouvez personnaliser la manière dont le serveur d'exécution traite les classes et les ressources.
public interface OpenAPIReader {
    void setConfiguration(OpenAPIConfiguration openAPIConfiguration);
    OpenAPI read(Set<Class<?>> classes, Map<String, Object> resources);
}

Pour que la fonction openapi-3.0 implémente le service OpenAPIReader spécifié, l'archive d'application doit contenir un fichier META-INF/services/io.swagger.oas.integration.OpenAPIReader. Ce fichier contient le nom complet de l'implémentation d'interface OpenAPIReader.

Vous pouvez également spécifier le nom complet de la classe d'implémentation avec io.swagger.oas.integration.OpenAPIConfiguration.getReaderClass().

OpenAPIScanner
Vous pouvez configurer les classes et les ressources qui sont traitées par le lecteur JAX-RS avec io.swagger.oas.integration.OpenAPIScanner. L'activation de ce service remplace l'analyse des annotations par Liberty.
public interface OpenAPIScanner {
    void setConfiguration(OpenAPIConfiguration openAPIConfiguration);
    Set<Class<?>> getClasses();
    Map<String, Object> getResources();
}

Comme pour OpenAPIConfigurationBuilder et OpenAPIReader, l'archive d'application doit inclure un fichier META-INF/service/io.swagger.oas.integration.OpenAPIScanner. Ce fichier contient le nom complet de l'implémentation d'interface OpenAPIScanner.

Vous pouvez également spécifier le nom complet de la classe d'implémentation avec io.swagger.oas.integration.OpenAPIConfiguration.getReaderClass().

Interfaces de programmation de service (SPI)

La fonction openapi-3.0 introduit une interface pour les bundles OSGi permettant de fournir une documentation OpenAPI V3 pour les API. Les utilisateurs SPI peuvent générer une documentation OpenAPI V3 pour les bundles OSGi qui sont basés sur une application ou sont des extensions de produit. Vous trouverez ces SPI dans le répertoire /wlp/dev/spi/ibm. Pour contribuer à votre documentation, enregistrez une implémentation de l'interface com.ibm.wsspi.openapi.OASProvider dans l'infrastructure OSGi.

OASProviderConfig
OASProviderConfig est une classe auxiliaire d'options de prise en charge qui peut être liée à un document OpenAPI V3 spécifique. Vous pouvez utiliser OASProviderConfig pour spécifier la langue dans laquelle vos documents sont écrits.
Restriction: seul le premier résultat renvoyé par OASProvider est utilisé lorsque openapi-3.0 génère de la documentation. openapi-3.0 ne prend pas en charge les configurations OASProvider multilingues. Spécifiez des fournisseurs qui renvoient un seul résultat.
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
L'interface OASProviderResult renvoie un seul document OpenAPI V3 en utilisant le modèle OpenAPI ou un texte YAML ou JSON formaté en tant que chaîne Java. Elle est associée à une configuration pour fournir des métadonnées sur le document.
public interface OASProviderResult {
    OpenAPI getOpenAPI();
    String getDocument();
    OASProviderConfig getOASProviderConfig();
}
OASProvider
Cette interface est le service principal que les utilisateurs SPI doivent implémenter pour contribuer à la documentation dans leur fonction OpenAPI V3. Pour contribuer à la documentation, vous devez enregistrer une interface OASProvider pour chaque racine de contexte que vous souhaitez documenter.
public interface OASProvider {
    List<OASProviderResult> getResults();
    String getContextRoot();
    boolean isPublic()     
    };
}