[17.0.0.1 and later]

Sobrescritura de campos de documento de Swagger 2.0

Utilice un atributo swaggerDefinition en un archivo server.xml para sobrescribir algunos campos en los documentos de Swagger 2.0 que proporcionan los puntos finales /docs y /explorer.

Antes de empezar

Primero debe añadir la característica apiDiscovery-1.0 al archivo server.xml y a continuación exponer la documentación de Swagger 2.0 en los puntos finales REST de Liberty. Complete los pasos 1 y 2 del procedimiento en Descubrimiento de la documentación de la API REST en un servidor Liberty.

Procedimiento

  1. Cree un fragmento swaggerDefinition para especificar un fragmento JSON o YAML Swagger que contenga campos para sobrescribir. Puede sobrescribir los campos info, schemes, consumes, produces y externalDocs.

    Por ejemplo, el fragmento de código swaggerDefinition siguiente cambia description, title y otros campos de info en las páginas HTML /explorer.

    {  
      "swagger" : "2.0",
      "info":{  
         "description":"My description",
         "version":"1.0.0",
         "title":"My title",
         "x-ibm-css":"${server.config.dir}/css/acme-banner.css",
         "termsOfService":"http://swagger.io/terms/",
         "contact":{  
            "email":"apiteam@swagger.io"
         },
         "license":{  
            "name":"Apache 2.0",
            "url":"http://www.apache.org/licenses/LICENSE-2.0.html"
         }
      }
    }

    Además de los valores de title y description, puede personalizar los elementos HTML de banner y logo en las páginas HTML /explorer. Dentro del campo info del fragmento de código swaggerDefinition, puede especificar un campo x-ibm-css para apuntar a una ubicación de un archivo CSS que altere la parte de banner y logotipo. Este archivo CSS tiene los siguientes requisitos de formato:

    • El archivo CSS debe especificar un elemento CSS .swagger-section #header.
    • Los nuevos logotipos deben utilizar el formato images/custom-logo.png, donde custom-logo es el nombre del archivo de imagen. Haga que la vía de acceso del archivo de logotipo sea relativa al archivo CSS.
    • El archivo CSS debe hacer referencia a la imagen de logotipo personalizado con la propiedad background-image establecida en el valor url(images/custom-logo.png).
    • El archivo de logotipo debe estar en el formato PNG.

    A continuación se muestra un ejemplo de un archivo CSS de modificación temporal:

    .swagger-section #header {
      background-image: url(images/custom-logo.png);
      background-repeat: no-repeat;
      background-color: lightslategray;
      background-position-x: 28px;
      padding-top: 20px;
      padding-right: 0px;
      padding-bottom: 20px;
      padding-left: 5px;
      height: 75px;
    }
  2. Añada un atributo swaggerDefinition al archivo server.xml.

    El valor del atributo swaggerDefinition debe ser uno de los siguientes:

    • La vía de acceso de un archivo local que finaliza con la extensión de archivo .json o .yaml. Esta vía de acceso puede incluir variables Liberty que están asociadas a directorios de tiempo de ejecución; por ejemplo:
      <apiDiscovery swaggerDefinition="${server.config.dir}/custom/swaggerDef.yaml" />
    • URL absoluto de un fragmento de código Swagger que empieza con http o https; por ejemplo:
      <apiDiscovery swaggerDefinition="http://mycompany.com/api/swaggerDef.json" />
    • La raíz de contexto de una aplicación desplegada en el servidor. La raíz de contexto empieza con una barra inclinada (/); por ejemplo:
      <apiDiscovery swaggerDefinition="/myApplication" />

    Para mejorar la experiencia de usuario de un servidor Liberty que contenga una aplicación web desplegada, el documento de Swagger de la aplicación web se utiliza como un fragmento swaggerDefinition. Todos los campos de la aplicación se modifican temporalmente en un documento de Swagger proporcionado por los puntos finales /docs aunque no haya un atributo swaggerDefinition definido en server.xml. Cuando se despliega una segunda aplicación web en un servidor, todos los campos afectados por optimización de aplicación única vuelven a sus valores predeterminados.


Icono que indica el tipo de tema Tema de tarea

Nombre de archivo: twlp_api_discovery_swagger_def.html