![[17.0.0.3 and later]](../ng_v17003plus.gif)
Personalización de la documentación de OpenAPI
Puede personalizar aspectos del documento OpenAPI maestro 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 cambios en el documento OpenAPI maestro y la interfaz de usuario.
Antes de empezar
Para obtener información sobre cómo crear y habilitar documentación de OpenAPI, consulte Generación de documentación de la 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 OpenAPI V3 de ejemplo.
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: API de aerolíneas description: Reservar vuelos y gestionar reservas 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 que están asociadas a 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).
.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 personalizado que se ha seleccionado para la supervisión es supervisado de forma continuada por Liberty hasta que se suprime.
Nota: Solo se supervisan los archivos de personalización para las actualizaciones. Los archivos CSS y de logotipo no se supervisan. Las URL no se supervisan.- Guarde el fragmento de código de personalización en un tipo de archivo YAML, YML o JSON en ${server.config.dir}/openapi/customization.tipo_archivo para utilizar la supervisión de archivos de personalización predeterminados.
- Opcional: Añada un elemento openapi con un atributo customization que hace 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, que es supervisado por Liberty. La vía de acceso puede incluir variables de Liberty que están asociadas con directorios de tiempo de ejecución, al igual que 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 archivos de personalización.
Liberty supervisa de forma continuada 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" />
![[17.0.0.3 and later]](../ng_v17003plus.gif)

Nombre de archivo: twlp_api_openapi_custom.html