![[17.0.0.3 and later]](../ng_v17003plus.gif)
OpenAPI V3 programming interfaces
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() }; }