Personalización de la documentación de OpenAPI

Puede personalizar aspectos del documento OpenAPI principal disponible en el punto final /api/docs y la interfaz de usuario OpenAPI en /api/explorer con elementos como el elemento externalDocs y el elemento info. Liberty supervisa los cambios en los archivos de personalización en las ubicaciones de vía de acceso predeterminadas para procesar y actualizar los cambios en el documento y la interfaz de usuario de OpenAPI principal.

Características estabilizadas: Las características de OpenAPI V3 , openapi-3.0 y openapi-3.1, están estabilizadas. Puede continuar utilizando las características. Sin embargo, la alternativa estratégica es utilizar una característica MicroProfile OpenAPI como mpOpenAPI-3.0.

Antes de comenzar

Para aprender a crear y habilitar la documentación de OpenAPI , consulte Generación de documentación de API REST con OpenAPI.

Genere documentación y represente un ejemplo de la interfaz de usuario personalizable utilizando la aplicación de aerolíneas de ejemplo OpenAPI V3.

Procedimiento

Defina una personalización en un fragmento de código OpenAPI.
Cree un fragmento de código que siga la estructura de la especificación de OpenAPI 3.0.0. El fragmento de código puede estar en un archivo YAML o JSON o disponible en un URL.
El elemento info proporciona título, descripción y otra información. Puede personalizar los valores de título y descripción. También puede personalizar la barra de cabecera para editar el logotipo, el recuadro de filtro y el botón de filtro. Dentro del campo info del fragmento de código de personalización, utilice un campo x-ibm-css para que apunte a la ubicación de un archivo CSS que indica el estilo de los elementos HTML de la barra de cabecera.
No es necesario que el fragmento de código se complete por sí mismo. El fragmento de código de ejemplo siguiente personaliza el elemento info, que apunta a un CSS que indica el estilo de la barra de cabecera de la interfaz de usuario de OpenAPI.
```
---
openapi: 3.0.0
info:
  title: Airlines APIs
  description: Book flights and manage reservations
  version: 2.1.0
  x-ibm-css: ${server.config.dir}/openapi/header.css
```
El CSS puede ser un archivo local o estar disponible en un URL. La vía de acceso puede incluir variables de Liberty asociadas con directorios de tiempo de ejecución.
Este archivo CSS tiene los requisitos de formato siguientes que se deben considerar válidos.
- El archivo CSS especifica, al menos, un elemento que empieza con .swagger-ui .headerbar.
- Solo se utilizan los contenidos que se especifican bajo elementos CSS que empiezan con .swagger-ui .headerbar.
- El archivo de logotipo personalizado referenciado por el archivo CSS debe estar en formato PNG.
- Un archivo de logotipo personalizado debe denominarse custom-logo.png y debe colocarse en images/custom-logo.png.
- La vía de acceso del archivo de logotipo debe ser relativa al archivo CSS.
- El archivo CSS debe hacer referencia a la imagen de logotipo con la propiedad background-image establecida en el valor url(images/custom-logo.png).
El fragmento de código de ejemplo siguiente muestra un archivo CSS de alteración temporal.
```
.swagger-ui .headerbar {
   background-color: #5f3345;
}
 .swagger-ui .headerbar .headerbar-wrapper {
   background-image: url(images/custom-logo.png);
}
 .swagger-ui .headerbar .filter-wrapper .filter-button {
    background: rgba(252, 48, 81, 0.53);
   color: #e8e8e8;
}
 .swagger-ui .headerbar .filter-wrapper input[type=text] {
        border: 1px solid #ebebeb;
}
```
Configure la supervisión de archivos para los archivos de personalización.

Puede guardar el archivo de personalización en la ubicación predeterminada para la supervisión automática o puede cambiar la configuración del servidor para definir una ubicación para el archivo. Si se ha especificado más de un archivo de personalización predeterminado, verá una salida de mensaje de aviso en la consola que indica el archivo de personalización supervisado y los archivos ignorados. El archivo de personalización que se selecciona para la supervisión lo supervisa de forma continua Liberty hasta que se suprime.

Nota: solo se supervisan las actualizaciones de los archivos de personalización. Los archivos CSS y de logotipo no se supervisan. Las URL no se supervisan.
1. Guarde el fragmento de código de personalización en el tipo de archivo YAML, YML o JSON en ${server.config.dir}/openapi/customization.file_type para utilizar la supervisión del archivo de personalización predeterminado.
2. Opcional: Añada un elemento openapi con un atributo customization que haga referencia al fragmento de código en el archivo de configuración del servidor Liberty .
  
  Las ubicaciones de definición de personalización predeterminadas no se supervisan cuando el atributo customization se ha establecido explícitamente. El atributo customization puede especificar un archivo YAML, YML o JSON, supervisado por Liberty. La vía de acceso puede incluir variables de Liberty asociadas con directorios de tiempo de ejecución, como en el ejemplo siguiente.
```
<openapi customization="${server.config.dir}/custom/customInfo.yaml" />
```
  El atributo customization también puede especificar un URL que devuelve un fragmento de código de OpenAPI.
```
<openapi customization="http://myWebsite.com/myCustomOpenAPI" />
```
Opcional: Inhabilite la supervisión de archivos para los archivos de personalización.

Liberty supervisa continuamente los archivos de personalización de forma predeterminada. Sin embargo, la supervisión de los archivos utiliza recursos de sistema adicionales. Si no tiene ningún archivo de personalización o si los archivos de personalización son estáticos y no cambian, es beneficioso desactivar la supervisión de archivos.

En el archivo de configuración del servidor del servidor, establezca el atributo booleano disableFileMonitor en true para el elemento openapi. Las ubicaciones de definición de personalización predeterminadas tampoco se supervisan cuando el atributo disableFileMonitor está establecido en true.
```
<openapi disableFileMonitor="true" />
```