Descubrimiento de la documentación de la API REST en un servidor Liberty

Puede descubrir la documentación de la API REST en un servidor Liberty utilizando la característica Descubrimiento de API para saber qué API REST están disponibles. Utilice la interfaz de usuario Swagger para iniciar los puntos finales REST disponibles.
[18.0.0.1 and later]Consejo: Puede utilizar la característica openapi-3.0 para descubrir la documentación de API REST. La característica openapi-3.0 se puede categorizar como la siguiente versión de la característica apiDiscovery-1.0. Puede actualizar un documento Swagger V2 que se crea con apiDiscovery-1.0 a OpenAPI V3. Consulte Generación de documentación de la API REST con OpenAPI.

Procedimiento

  1. Añada la característica apiDiscovery-1.0 a un gestor de características en el archivo server.xml del servidor Liberty cuyas API REST disponibles desea descubrir.

    La característica apiDiscovery-1.0 habilita los paquetes de descubrimiento de API REST en el producto. La característica también muestra documentación de puntos finales REST de Liberty como, por ejemplo, JMX, si la configuración de servidor utiliza la característica restConnector-1.0, y colectivos, si la configuración de servidor utiliza la característica collectiveController-1.0.

    La característica apiDiscovery-1.0 habilitada en un servidor de controlador colectivo de Liberty busca las API REST disponibles en el controlador y en sus servidores miembro con la característica apiDiscovery-1.0.

    Asegúrese de que la configuración de servidor tiene todas las características necesarias para la aplicación desplegada como, por ejemplo, jaxrs-2.0. Modifique los puertos de modo que el servidor pueda abrir sus puertos HTTP.

    Si desea visualizar la documentación de API REST privada, configure una entrada de objeto de servicio de almacén de claves y valores de registro de usuarios en el archivo server.xml.

    [17.0.0.1 and later]Sin embargo, si desea mostrar únicamente la documentación de API REST pública, añada una entrada de objeto de almacén de claves sólo si desea acceder al documento mediante HTTPS. El acceso a la documentación pública mediante HTTP no requiere una entrada de objeto de almacén de claves ni valores del registro de usuarios.

    El archivo server.xml siguiente tiene la característica apiDiscovery-1.0:

    <server>
        <featureManager>
            <feature>apiDiscovery-1.0</feature>
        </featureManager>
    
        <httpEndpoint id="defaultHttpEndpoint"
                      host="*"
                      httpPort="8010"
                      httpsPort="8020"/>
    
        <keyStore id="defaultKeyStore" password="Liberty"/>
      
        <basicRegistry id="basic" realm="ibm/api">
            <user name="bob" password="bobpwd" />
        </basicRegistry>
    </server>
  2. Visualice la documentación de Swagger 2.0 en los puntos finales REST de Liberty.

    Si la aplicación web contiene dos o más instancias de la clase javax.ws.rs.core.Application para funcionar correctamente con la característica de descubrimiento de API, cada aplicación necesita un valor javax.ws.rs.@ApplicationPath exclusivo o url-mapping definido en el archivo web.xml.

    Habilite la característica apiDiscovery-1.0 para fusionar la documentación actual con la documentación que encuentra durante la exploración de anotaciones. El producto busca un archivo META-INF/stub/swagger.json o META-INF/stub/swagger.yaml en el módulo web. Si la característica encuentra uno de los archivos, la característica genera un documento Swagger que contiene tanto el contenido de archivo como las anotaciones JAX-RS y Swagger que están en el módulo web. Puede utilizar esta característica para documentar servlets no JAX-RS porque la documentación se fusiona automáticamente con las partes de JAX-RS.Puede configurar la ubicación de la documentación de la API de cualquiera de estas dos formas:

    • Utilice el método getDocument de la interfaz com.ibm.wsspi.rest.api.discovery.APIProvider de SPI.

      El método getDocument permite a los paquetes OSGi de características de extensión aportar documentos de la API REST a la documentación maestra general. Para este release, los únicos DocType soportados son DocType.Swagger_20_JSON y DocType.Swagger_20_YAML. Los implementadores de esta interfaz pueden devolver el documento JSON o YAML serializado como un valor java.lang.String o pueden pasar en una referencia de archivo (con el prefijo file:///) a la ubicación de archivo JSON o YAML.

    • Utilice una aplicación web desplegada.

      Cada módulo web puede contribuir con su propio documento de API REST. Varios archivos WAR dentro de un archivo aplicación empresarial (EAR) puede tener distintos documentos de Swagger 2.0.

      La forma más fácil de visualizar la documentación de módulos web consiste en incluir un archivo swagger.json o swagger.yaml en la carpeta META-INF correspondiente. Durante el despliegue de una aplicación, la característica de Descubrimiento de API busca un valor META-INF/swagger.json para cada uno de los módulos web. Si no se encuentra un valor META-INF/swagger.json, la característica de descubrimiento de API busca un valor META‐INF/swagger.yaml.

      Otraa forma de mostrar la documentación de API REST para un módulo web es en un archivo de configuración server.xml. Coloque un elemento webModuleDoc para cada módulo web en un elemento apiDiscovery padre. Por ejemplo:

      <apiDiscovery>
         <webModuleDoc contextRoot="/30ExampleServletInEar" enabled="true" docURL="/swagger.json" />	
         <webModuleDoc contextRoot="/22ExampleServlet" enabled="false" />
         <webModuleDoc contextRoot="/custom" enabled="true" docURL="http://petstore.swagger.io/v2/swagger.json" />
      </apiDiscovery>

      El elemento webModuleDoc debe tener un atributo contextRoot para identificar de forma exclusiva el módulo web cuya documentación desea visualizar.

      Un atributo opcional, enabled, conmuta el descubrimiento de la API para un módulo web. El valor predeterminado de este atributo es true.

      El atributo docURL especifica dónde encontrar la documentación para el módulo web. El valor docURL puede empezar con una barra diagonal (/) de forma que el URL es relativo a la raíz de contexto; por ejemplo, /30ExampleServletInEar/swagger.json. O bien, el valor docURL puede empezar con http o https para un URL absoluto que identificar la ubicación completa de la documentación.

      Si la aplicación web no proporciona un archivo swagger.json o swagger.yaml y la aplicación contiene recursos anotados JAX-RS, puede generar automáticamente el documento Swagger. La configuración de servidor debe tener la característica apiDiscovery-1.0 y la característica jaxrs-1.1 o jaxrs-2.0; por ejemplo:
      <featureManager>
          <feature>apiDiscovery-1.0</feature>
          <feature>jaxrs-1.1</feature>
      </featureManager>
      El producto explora todas las clases en la aplicación web en busca de anotaciones JAX-RS y Swagger, buscando clases con anotaciones @Path, @Api y @SwaggerDefinition. El producto también genera automáticamente un documento Swagger correspondiente durante el despliegue o el inicio de aplicación web.

      También puede utilizar la característica apiDiscovery-1.0 para fusionar la documentación generada previamente con la documentación que encuentra durante la exploración de anotaciones. El producto busca un archivo META-INF/stub/swagger.json o META-INF/stub/swagger.yaml en el módulo web. Si la característica encuentra uno de estos archivos, genera un documento Swagger que contiene tanto el contenido del archivo como las anotaciones JAX-RS y Swagger que están en el módulo web. Puede utilizar esta característica para documentar servlets no JAX-RS porque la documentación se fusiona automáticamente con las partes de JAX-RS.

      Esta técnica también puede utilizarse para ignorar limitaciones de anotación como, por ejemplo, las definiciones de seguridad visualizadas. Por ejemplo, el siguiente swagger.json, en META-INF/stub, permite que las anotaciones hagan referencia a estas definiciones:

      {
        "swagger" : "2.0",
        "securityDefinitions" : {
          "petstore_auth" : {
            "type" : "oauth2",
            "authorizationUrl" : "http://petstore.swagger.io/api/oauth/dialog,"
            "flow" : "implicit",
            "scopes" : {
              "write_pets" : "modify pets in your account",
              "read_pets" : "read your pets"
            }
          },
          "api_key" : {
            "type" : "apiKey",
            "name" : "api_key",
            "in" : "header"
          }
        }
      }
  3. Descubra la documentación de la API.

    Tras configurar la ubicación de la documentación de la API, puede descubrirla de las formas siguientes:

    • Utilice el punto final GET https://host:puerto_https/ibm/api/docs.

      Este punto final proporciona un documento Swagger 2.0 válido con todas las API REST de Liberty disponibles fusionadas en un solo documento. Esto es útil para aplicaciones de consumidor que desean navegar a través de programas por el conjunto de API disponibles como, por ejemplo, una solución de gestión de API. La inclusión de una cabecera Accept opcional con un valor application/yaml proporciona el documento Swagger 2.0 en formato YAML. Este punto final tiene un parámetro de consulta opcional de cardinalidad múltiple que se llama root que puede filtrar las raíces de contexto encontradas. Por ejemplo, una llamada a GET https://host:puerto_https/ibm/api/docs?root=/myApp recupera un documento Swagger 2.0 que solo tiene la documentación para la raíz de contexto myApp.

    • Utilice el punto final GET https://host:puerto_https/ibm/api/explorer.

      Este punto final proporciona una página representada en HTML atractiva que muestra el contenido del URL /ibm/api/docs. Esta página sigue el mismo patrón que el ejemplo en línea estándar (http://petstore.swagger.io/) para que los usuarios puedan iniciar la API REST. Este punto final le ayuda a explorar las API REST disponibles en un servidor Liberty y quizás a iniciarlas desde la página.

      Un cuadro de entrada de filtro en la página permite a una lista separada por comas de raíces de contexto filtrar el contenido.

    • Para un controlador colectivo, utilice el punto final GET https://host:puerto_https/ibm/api/collective/docs.

      Este punto final en el controlador colectivo proporciona un documento Swagger 2.0 válido con las API REST disponibles desde el controlador colectivo y sus miembros con la característica apiDiscovery-1.0 habilitada fusionados en un solo documento. Esto es útil para aplicaciones de consumidor que desean navegar a través de programas por el conjunto de API disponibles como, por ejemplo, una solución de gestión de API. La inclusión de una cabecera Accept opcional con un valor application/yaml proporciona el documento Swagger 2.0 en formato YAML.

      [17.0.0.1 and later]Este punto final tiene un parámetro de consulta opcional de varias cardinalidades llamado root.

      El root puede filtrar las raíces de contexto encontradas. Por ejemplo, una llamada a GET https://host:puerto_https/ibm/api/collective/docs?root=/myApp recupera un documento Swagger 2.0 que solo tiene la documentación para la raíz de contexto myApp.

      [16.0.0.x]Para versiones anteriores a 17.0.0.1, este punto final tiene dos parámetros de consulta opcionales de cardinalidad múltiple denominados root y serverID. El parámetro de consulta root es el mismo que antes. El parámetro de consulta serverID puede filtrar las API REST disponibles desde un servidor Liberty. El formato de serverID es nombre_host,dir_usuario,nombre_servidor. Por ejemplo, una llamada a GET https://host:puerto_https/ibm/api/collective/docs?serverID=samplehost.com:8020,/users/admin/wlp/usr,server1 recupera un documento Swagger 2.0 que solo tiene la documentación para las API REST disponibles desde el servidor Liberty con el serverID especificado.

    • Para un controlador colectivo, utilice el punto final GET https://host:puerto_https/ibm/api/collective/explorer.

      Este punto final en el controlador colectivo proporciona una página representada en HTML atractiva que muestra el contenido del URL /ibm/api/collective/docs. Este punto final le ayuda a explorar las API REST disponibles en todo el colectivo y quizás iniciarlas desde la página. Un cuadro de entrada de filtro en la página permite a una lista separada por comas de raíces de contexto e ID de servidor filtrar el contenido. El formato del ID del servidor es "nombre_host,dir_usuario,nombre_servidor". El ID de servidor debe escribirse entre comillas ("). Para probar las API utilizando el botón Pruébelo, debe configurar el Compartimiento de solicitud entre orígenes (CORS) en el server.xml del servidor de miembros.​

      [16.0.0.x]Para versiones anteriores a 17.0.0.1, un fragmento de código como el del ejemplo siguiente es necesario en el server.xml del servidor miembro que proporciona la API /IBMJMXConnectorREST/mbeanCount.
      <cors domain="/IBMJMXConnectorREST/mbeanCount"
            allowedOrigins="https://controller_hostname:https_port"
            allowedMethods="GET,POST,DELETE,PUT,PATCH,OPTIONS"
            allowedHeaders="Content-Type,api_key,Authorization"
            allowCredentials="true" />

      Para obtener información sobre la configuración de CORS, consulte Configuración del uso compartido de recursos de orígenes cruzados en un servidor Liberty.

      Nota: El requisito de CORS sólo es aplicable a la versión colectiva de la interfaz de usuario Swagger (https://host:puerto_https/ibm/api/collective/explorer).
    • [17.0.0.1 and later]Utilice otros puntos finales para mostrar la documentación de REST pública.

      A diferencia de los puntos finales mencionados anteriormente, el acceso a estos puntos finales no requiere una entrada de objeto de servicio de almacén de claves ni valores de registro de usuarios. Sin embargo, puede establecer una entrada de objeto de servicio de almacén de claves para acceder a los puntos finales mediante HTTPS.

      De forma predeterminada hay cuatro puntos finales disponibles para un controlador de colectivo:
      • GET http://host:puerto_http/api/docs
      • GET http://host:puerto_http/api/explorer
      • GET http://host:puerto_http/api/collective/docs
      • GET http://host:puerto_http/api/collective/explorer
      De forma predeterminada hay dos puntos finales disponibles para un servidor:
      • GET http://host:puerto_http/api/docs
      • GET http://host:puerto_http/api/explorer

      Puede cambiar el URL de los puntos finales públicos con el atributo publicURL en server.xml. Por ejemplo, si se establece la configuración siguiente en server.xml, la documentación de API REST pública estará disponible con GET http://host:puerto_http/myAPI/docs y http://host:puerto_http/myAPI/explorer:

      <apiDiscovery publicURL="myAPI" />

      De forma predeterminada, todos los puntos finales de API REST con los que han contribuido las aplicaciones web desplegadas, con la excepción de los puntos finales de servidor internos como por ejemplo las API REST de conector REST JMX, se visualizan en la documentación de API REST pública. Puede establecer un atributo public="false" para un módulo web para que no visualice las API REST mostrada por el módulo. Por ejemplo, si se añade la configuración siguiente a un server.xml, las API REST del módulo web no se visualizarán en la documentación de API REST pública:

      <apiDiscovery publicURL="myAPI">
         <webModuleDoc contextRoot="/22ExampleServlet" public="false" />
      </apiDiscovery>
    • [17.0.0.1 and later]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.

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

    • [17.0.0.1 and later]Para un controlador colectivo, utilice una consulta de servicios de colectivo para listar todas las API RESTful públicas (servicios) disponibles en todo el colectivo.

    Después de habilitar la característica apiDiscovery-1.0, el bean de gestión (MBean) que tiene el valor de ObjectName WebSphere:feature=apiDiscovery,name=APIDiscovery está registrado en el MBeanServer de Liberty. Este bean gestionado (MBean) proporciona los atributos siguientes:

    • El atributo DocumentationURL es el URL completo del punto final /ibm/api/docs y muestra la documentación de JSON o YAML en bruto.
    • El atributo ExplorerURL es el URL completo del punto final /ibm/api/explorer y muestra la interfaz de usuario representada de la documentación.

    Puede utilizar este bean gestionado para saber si el descubrimiento de API REST está habilitado y donde puede alcanzarlo un cliente.

Ejemplo

Puede encontrar más información sobre el descubrimiento de API REST en Interfaces OpenAPI y en el sitio web WASdev.

Vídeo flash de IBM MediaCenter con presentación de sonido Vea: El vídeo Descubrimiento de la API Liberty de IBM WebSphere Application Server en IBM MediaCenter proporciona ejemplos y enlaces a vídeos de demostración. (V8.5.5.9)


Icono que indica el tipo de tema Tema de tarea

Nombre de archivo: twlp_api_discovery.html