One of the most used terms these days is API Economy. It is a vast domain that covers the exposure and invocation of services from and to anywhere. At the center of the API Economy are RESTful APIs because they are, by nature, language-neutral and by far the most widely used type of API today.
Liberty supports the creation and deployment of REST APIs in a variety of forms (JAX-RS, Java EE servlet, OSGi web apps, REST Handler, etc) but, until recently, there was not an easy way of exposing all these REST assets from your Liberty instance. This article will go over the new capabilities available in Liberty to close this gap.
The API discovery feature in Liberty
Starting with Liberty v126.96.36.199 we added a new feature called
apiDiscovery-1.0. This feature aggregates the Swagger-based definitions from all deployed applications (including runtime endpoints) into a single Swagger document, which can be consumed in native JSON or YAML formats or through our Swagger User Interface.
If you don’t have the
apiDiscovery-1.0 feature in your Liberty installation you can pull it from the repository by running the command:
wlp/bin installUtility install apiDiscovery-1.0
The first release of this feature, in Liberty v188.8.131.52, focused on exposing pre-generated Swagger documents in JSON format by searching for a
swagger.json file inside the
META-INF folder of every deployed web module. All these documents are aggregated internally to produce a single Swagger definition, available through a new Liberty REST endpoint at
Here is a sample of minimal configuration needed in your
server.xml in order to reach that endpoint:
<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>
This JSON definition is useful for API Management solutions or any graphical user interface that wants to display the definitions of those RESTful APIs. The following diagrams depicts this relationship:
Liberty’s new Swagger User Interface
In fact, this is exactly what our Swagger User Interface (based on the Swagger UI open source version) does. It renders the aggregated definition from
/ibm/api/docs and displays an attractive human-friendly UI at
Developers familiar with StrongLoop’s Explorer will appreciate the design decision of keeping the UIs consistent at the
From this user interface, just like the open source version and StrongLoop’s version, you can view all RESTful endpoints and actually invoke them right from your browser by filling in the corresponding fields and clicking the Try it out! button. It’s a handy client built into your browser. Another nice feature of our UI, which is not available in other Swagger renderings, is a filter box that lets you focus on the applications you really care about. If, in the example above, I typed
/ibm/api/markham/traffic, only the APIs for the Traffic application would be shown in the UI.
From the screenshot above you’ll notice that Liberty’s JMX Connector APIs are also appearing. These APIs were contributed to our API discovery aggregator through our OSGi SPI,
com.ibm.wsspi.rest.api.discovery.APIProvider. This very simple interface has a single method, called
getDocument, which allows OSGi bundles (web bundles or regular bundles) to contribute REST API definitions into the aggregator.
So if you enable
apiDiscovery-1.0 and any internal Liberty runtime that exposes REST APIs (
collectiveController-1.0, etc), you will see those APIs in both the aggregated document (
/ibm/api/docs) and in the UI (
/ibm/api/explorer)! This is also valid for any extensions of Liberty, where their bundles can similarly expose their REST APIs through this SPI.
<webModule>/META-INF/swagger.json and the SPI, using Liberty v184.108.40.206 you also specify another location of your pre-generated Swagger definition by using the
webModuleDoc configuration element, a child of
<apiDiscovery> <webModuleDoc contextRoot="/30ExampleServletInEar" docURL="/swagger.json" /> <webModuleDoc contextRoot="/custom" docURL="http://petstore.swagger.io/v2/swagger.json" /> </apiDiscovery>
The first entry, for web module
/30ExampleServletInEar, is specifying that a
swagger.json is available relative to its context root, therefore at
/30ExampleServletInEar/swagger.json, while the second entry, for web module
/custom, is specifying the absolute URL of a remote document repository.
The next few Beta releases after Liberty v220.127.116.11 packed a lot more good stuff! Let’s go through some of them.
New Liberty beta functionality
JAX-RS 1.1/2.0 and Swagger annotation support
We now support auto-generation of Swagger definitions from JAX-RS and Swagger annotations! This is a very important feature, since it supports the famous bottom-up development where the documentation comes from the code itself. Just enable
apiDiscovery-1.0, drop your JAX-RS application into the
dropins directory (with either
jaxrs-2.0 enabled) and watch your APIs come out inside
The Liberty REST API Discovery framework now interchangeably supports both JSON and YAML formats. You can provide either format and query either format; it all merges and renders perfectly! This means you can now provide Liberty with your
swagger.yaml document inside
<webModule>/META-INF, and also use an
Accept header of
application/yaml when querying
/ibm/api/docs and youâ€™ll be returned the aggregated Swagger 2.0 document in YAML format!
You can also continue to use the
/ibm/api/explorer as before, regardless of whether some documents are being provided as JSON and other as YAML.
You can now provide a
swagger.yaml document inside
<webModule>/META-INF/stub and Libertyâ€™s REST API Discovery framework will automatically merge those contents with any JAX-RS annotations that we find. This is useful for the scenarios where your web module has regular servlets (non JAX-RS) that you want to document in addition to any JAX-RS endpoints. You can also use this methodology to augment your existing annotations with extra information such as security constraints.
Collective aggregation and Explorer
There is now a collective-wide Swagger 2.0 document of your REST APIs. Just add
apiDiscovery-1.0 to your collective controller and to any collective member that wants to expose REST APIs, and when you query
/ibm/api/collective/docs in the collective controller you will see a Swagger 2.0 document that aggregates all of the REST APIs being exposed in the collective!
We also have its visual counterpart, available at
/ibm/api/collective/explorer. It is very similar to
/ibm/api/explorer, except that this endpoint is only available in the Liberty collective controller. It will also show all REST APIs that are available from any of the members of that Liberty collective. The filter box for the collective UI also has been enhanced to allow filtering based on collective member ID (a comma-separated tuple of the memberâ€™s hostName, URL-encoded
wlp/usr path, and
You can now subscribe to receive real-time updates on the REST APIs of a Liberty server. This means that you can instantly know if a new application has been deployed with new REST endpoints, or if an existing set of endpoints has been dynamically removed. Simply subscribe to the
/ibm/api/docs/subscription endpoint and youâ€™ll receive a WebSocket URL which you can open and listen for updates. You can also subscribe for collective-wide notifications by calling
/ibm/api/collective/docs/subscription on the collective controller.
Context root document serving
Any web module in Liberty that is providing Swagger 2.0 documentation through any means (i.e. annotations, pre-generated, stub merging, etc) can now directly reach the documentation by invoking
<webModule_contextRoot>/swagger.yaml. Except in cases where the application has explicitly blocked access to it, the REST API Discovery framework auto-detects this request from the web container and automatically responds with the Swagger 2.0 document. This provides the exact same effect as querying
For more information please visit Knowledge Center.