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 invocar los puntos finales REST disponibles.
Procedimiento
- 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 expone documentación de puntos finales REST de Liberty como, por ejemplo, JMX, si la configuración del servidor utiliza la característica restConnector-1.0 y colectivos, si la configuración del servidor utiliza la característica collectiveController-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, servlet-3.0, jsp-2.2, etc. Asimismo, asegúrese de que los puertos y los valores de registro de usuario son correctos para la aplicación desplegada.
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>
- Exponga la documentación de Swagger 2.0 en 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 trabajar 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 exponer 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 buscar un valor META‐INF/swagger.yaml
Otra forma de exponer la documentación de la 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 exponer.
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:
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.<featureManager> <feature>apiDiscovery-1.0</feature> <feature>jaxrs-1.0</feature> </featureManager>
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 anotaciones como, por ejemplo, la exposición de definiciones de seguridad. Por ejemplo, el siguiente swagger.json, inside 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" } } }
- Utilice el método getDocument de la
interfaz
com.ibm.wsspi.rest.api.discovery.APIProvider de
SPI.
- 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/), así que los usuarios pueden invocar la API REST. Este punto final le ayuda a explorar las API REST disponibles en un servidor Liberty y, quizás, las invoca 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. Este sistema de filtrado funciona como el parámetro de consulta root. Puede probar las API proporcionando los valores de entrada necesarios y pulsar Pruébelo.
- 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.
- Utilice el punto final GET
https://host:puerto_https/ibm/api/docs.
Subtemas
- Suscribirse a las actualizaciones de API REST de Liberty
Ahora la característica de descubrimiento de API REST de Liberty expone una nueva API REST, /ibm/api/docs/subscription, que permite a los usuarios suscribirse a cualquier actualización de API REST, por ejemplo las API nuevas que están disponibles o las API antiguas que se eliminan. Esto es útil cuando un usuario desea que se le notifique inmediatamente cualquier cambio en los puntos finales proporcionados por una instancia Liberty concreta. - Puntos finales REST para distribuir API en IBM API Connect
Utilice el punto final REST, que es una ubicación central para que tanto los usuarios internos, como los usuarios de Cloud Liberty, visualicen, llamen y distribuyan API en IBM® API Connect.


http://www14.software.ibm.com/webapp/wsbroker/redirect?version=cord&product=was-nd-mp&topic=twlp_api_discovery
Nombre de archivo:twlp_api_discovery.html