OpenAPI V3 programming interfaces

You can use the following programming interfaces to extend the openapi-3.0 feature. See the OpenAPI V3 sample application on GitHub to build your own OpenAPI models and generate documentation.

Stabilized features: The OpenAPI V3 features, openapi-3.0 and openapi-3.1, are stabilized. You can continue to use the features. However, the strategic alternative is to use a MicroProfile OpenAPI feature such as mpOpenAPI-3.0.

Application programming interfaces (APIs)

You can use the io.swagger.oas.integration programming interfaces to configure parameters that are related to OpenAPI V3 processing in Liberty. These parameters are in the JAR files in the /wlp/dev/api/third-party directory.

OpenAPIConfiguration
The io.swagger.oas.integration.OpenAPIConfiguration interface is a container for all configuration parameters in OpenAPI V3 processing. With this interface you can provide a complete OpenAPI model, disable or configure annotation scanning, and provide other helper services. These services include a custom reader and 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
The io.swagger.oas.integration.OpenAPIConfigurationBuilder interface is the main service that enables customization of the OpenAPI V3 processing in Liberty. You can use the OpenAPIConfigurationBuilder to receive framework-dependent environment variables that it processes when it builds a new OpenAPIConfiguration object.

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

The following example code uses OpenAPIConfigurationBuilder to build an OpenAPI model with the OpenAPI V3 sample application.


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

For the openapi-3.0 feature to start the OpenAPIConfigurationBuilder, the application archive must have a META-INF/services/io.swagger.oas.integration.OpenAPIConfigurationBuilder file. The content of this file is the fully qualified name of the OpenAPIConfigurationBuilder interface implementation. For this example, the value is com.example.AirlinesAPIs. For more information about the format of this file, see the Java™ SE documentation on java.util.ServiceLoader.

OpenAPIReader
The io.swagger.oas.integration.OpenAPIReader interface allows an application developer to provide a custom JAX-RS reader instead of the default implementation of the JAX-RS reader. When you enable the OpenAPIReader service, you can customize how the runtime server processes classes and resources. 
public interface OpenAPIReader {
    void setConfiguration(OpenAPIConfiguration openAPIConfiguration);
    OpenAPI read(Set<Class<?>> classes, Map<String, Object> resources);
}

For the openapi-3.0 feature to implement the specified OpenAPIReader, the application archive must have a META-INF/services/io.swagger.oas.integration.OpenAPIReader file. This file contains the fully qualified name of the OpenAPIReader interface implementation.

You can also specify the fully qualified name of the implementation class with io.swagger.oas.integration.OpenAPIConfiguration.getReaderClass().

OpenAPIScanner
You can configure which classes and resources are processed by the JAX-RS reader with io.swagger.oas.integration.OpenAPIScanner. Enabling this service overrides annotation scanning by Liberty. 
public interface OpenAPIScanner {
    void setConfiguration(OpenAPIConfiguration openAPIConfiguration);
    Set<Class<?>> getClasses();
    Map<String, Object> getResources();
}

Similar to both OpenAPIConfigurationBuilder and OpenAPIReader, the application archive must include a META-INF/service/io.swagger.oas.integration.OpenAPIScanner file. This file contains the fully qualified name of the OpenAPIScanner interface implementation.

You can also specify the fully qualified name of the implementation class with io.swagger.oas.integration.OpenAPIConfiguration.getReaderClass().

Service programming interfaces (SPIs)

The openapi-3.0 feature introduces an interface for OSGi bundles to provide OpenAPI V3 documentation for APIs. SPI users can generate OpenAPI V3 documentation for OSGi bundles that are application-based or product extensions. You can find these SPIs in the /wlp/dev/spi/ibm directory. To contribute your documentation, register an implementation of the com.ibm.wsspi.openapi.OASProvider interface into the OSGi framework.

OASProviderConfig
The OASProviderConfig is a helper class of support options that can be linked to a specific OpenAPI V3 document. You can use OASProviderConfig to specify the language that your documents are written in.
Restriction: Only the first result that is returned from OASProvider is used when openapi-3.0 generates documentation. openapi-3.0 does not support OASProvider configurations for multiple languages. Specify providers that return only one result.
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
The OASProviderResult interface returns a single OpenAPI V3 document by using either the OpenAPI model or either a YAML or JSON text that is formatted as a Java String. It has an attached configuration to provide metadata about the document.
public interface OASProviderResult {
    OpenAPI getOpenAPI();
    String getDocument();
    OASProviderConfig getOASProviderConfig();
}
OASProvider
This interface is the main service that SPI users must implement to contribute documentation into their OpenAPI V3 feature. To contribute documentation, you must register one OASProvider for each context root that you want to document. 
public interface OASProvider {
    List<OASProviderResult> getResults();
    String getContextRoot();
    boolean isPublic()     
    };
}