![[17.0.0.3 and later]](../ng_v17003plus.gif)
Interfaces de programación OpenAPI V3
Interfaces de programación de aplicación (API)
Puede utilizar las interfaces de programación io.swagger.oas.integration para configurar parámetros que están relacionados con el proceso OpenAPI V3 en Liberty. Estos parámetros están en los archivos JAR del directorio /wlp/dev/api/third-party.
- OpenAPIConfiguration
- La interfaz io.swagger.oas.integration.OpenAPIConfiguration es un contenedor para todos los parámetros de configuración en el proceso OpenAPI V3. Con esta interfaz, puede proporcionar un modelo completo de OpenAPI, inhabilitar o configurar la exploración de anotaciones y proporcionar otros servicios de ayuda.
Estos servicios incluyen un lector y un explorador personalizados.
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
- La interfaz io.swagger.oas.integration.OpenAPIConfigurationBuilder es el servicio principal que permite la personalización del proceso OpenAPI V3 en Liberty. Puede utilizar OpenAPIConfigurationBuilder para recibir variables de entorno que dependen de la infraestructura que procesa cuando crea un nuevo objeto OpenAPIConfiguration.
public interface OpenAPIConfigurationBuilder { OpenAPIConfiguration build(Map<String, Object> environment); }
El código de ejemplo siguiente utiliza OpenAPIConfigurationBuilder para crear un modelo OpenAPI con la aplicación de muestra de 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("Obtener la lista de aerolíneas disponibles").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; } }
Para que la característica openapi-3.0 inicie OpenAPIConfigurationBuilder, el archivado de la aplicación debe tener un archivo META-INF/services/io.swagger.oas.integration.OpenAPIConfigurationBuilder. El contenido de este archivo es el nombre completo de la implementación de la interfaz OpenAPIConfigurationBuilder. Para este ejemplo, el valor es com.example.AirlinesAPIs. Si desea más información sobre el formato de este archivo, consulte la documentación de Java™ SE en java.util.ServiceLoader.
- OpenAPIReader
- La interfaz io.swagger.oas.integration.OpenAPIReader permite a un desarrollador de aplicaciones proporcionar un lector JAX-RS personalizado de la implementación predeterminada del lector JAX-RS. Al habilitar el servicio OpenAPIReader, puede personalizar cómo procesa el servidor de tiempo de ejecución clases y recursos.
public interface OpenAPIReader { void setConfiguration(OpenAPIConfiguration openAPIConfiguration); OpenAPI read(Set<Class<?>> classes, Map<String, Object> resources); }
Para que la característica openapi-3.0 implemente el OpenAPIReader especificado, el archivo de la aplicación debe tener un archivo META-INF/services/io.swagger.oas.integration.OpenAPIReader. Este archivo contiene el nombre completo de la implementación de la interfaz OpenAPIReader.
También puede especificar el nombre completo de la clase de implementación con io.swagger.oas.integration.OpenAPIConfiguration.getReaderClass().
- OpenAPIScanner
- Puede configurar qué clases y recursos procesa el lector JAX-RS con io.swagger.oas.integration.OpenAPIScanner. La habilitación de este servicio altera temporalmente la exploración de anotaciones por parte de Liberty.
public interface OpenAPIScanner { void setConfiguration(OpenAPIConfiguration openAPIConfiguration); Set<Class<?>> getClasses(); Map<String, Object> getResources(); }
Similar a ambos, OpenAPIConfigurationBuilder y OpenAPIReader, el archivo de la aplicación debe incluir un archivo META-INF/service/io.swagger.oas.integration.OpenAPIScanner. Este archivo contiene el nombre completo de la implementación de la interfaz OpenAPIScanner.
También puede especificar el nombre completo de la clase de implementación con io.swagger.oas.integration.OpenAPIConfiguration.getReaderClass().
Interfaces de programación de servicios (SPI)
La característica openapi-3.0 presenta una interfaz para paquetes OSGi para proporcionar documentación de OpenAPI V3 para API. Los usuarios de SPI pueden generar documentación de OpenAPI V3 para paquetes OSGi que son extensiones basadas en aplicación o extensiones de producto. Puede encontrar estas SPI en el directorio /wlp/dev/spi/ibm. Para contribuir en la documentación, registre una implementación de la interfaz com.ibm.wsspi.openapi.OASProvider en la infraestructura OSGi.
- OASProviderConfig
- OASProviderConfig es una clase auxiliar de opciones de soporte que se pueden enlazar a un documento OpenAPI V3 específico. Puede utilizar OASProviderConfig para especificar el idioma en el que están escritos los documentos. Restricción: Solo se utiliza el primer resultado devuelto de OASProvider cuando openapi-3.0 genera documentación. openapi-3.0 no admite configuraciones de OASProvider para varios idiomas. Especifique proveedores que solo devuelvan un resultado.
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
- La interfaz OASProviderResult devuelve un solo documento OpenAPI V3 utilizando el modelo de OpenAPI o un texto YAML o JSON que tiene un formato de serie Java. Tiene una configuración adjunta para proporcionar metadatos sobre el documento.
public interface OASProviderResult { OpenAPI getOpenAPI(); String getDocument(); OASProviderConfig getOASProviderConfig(); }
- OASProvider
- Esta interfaz es el servicio principal que los usuarios de SPI deben implementar para contribuir con documentación sobre su característica OpenAPI V3. Para contribuir con documentación, debe registrar un OASProvider para cada raíz de contexto que desea documentar.
public interface OASProvider { List<OASProviderResult> getResults(); String getContextRoot(); boolean isPublic() }; }