Every day new APIs are being deployed and existing APIs are being adopted by new clients. The need for a consistent way to share the contract (the Swagger definition) between server and clients exist in all levels, such on-premise and local/public/hybrid cloud environments.

This blog is a follow-up to our WebSphere Liberty API discovery introduction and takes you on the journey of adding Swagger support to your assets, exposing them on-premise, pushing them into the cloud, and finally integrating them with a powerful API management solution.

We start by taking a closer look at our sample application which has Swagger annotations as well as a pre-generated Swagger document for the servlet portion of the web module. You’ll learn how these annotations augment existing JAX-RS annotations, and how it is all rendered into WebSphere Liberty’s native Swagger UI:

To recap from the last video, there are three patterns for exposing Swagger in Liberty:

  1. Using annotations (bottom-up)
  2. Placing a pre-generated Swagger document inside META-INF (top-down)
  3. Using annotations together with a pre-generated Swagger document inside META-INF/stub (hybrid)

Now that you’re familiar with deploying applications on-premise, let’s take a look at how to lift-and-shift your applications into the cloud! This is easily done by using Cloud Foundry, which underpins IBM Cloud:

Now you have assets running on-prem and in the cloud! The last step in this API journey is to integrate your APIs with an API management framework. IBM’s new API Connect framework is a great place to manage and secure your APIs. In this next video I demonstrate how you can easily integrate your WebSphere Liberty’s APIs with API Connect within minutes! Check it out:

As a developer, you can now easily test your application from end-to-end, including how it is exposed via API Connect, by using WebSphere Liberty’s Swagger UI to test the application endpoints and push them into API Connect. Administrators and/or business users can use API Connect’s toolkit to create a product.json (or product.yaml) that they can check into their source repository, and this asset can be used to trigger the /ibm/api/docs/apiconnect endpoint (i.e. via curl) in a continuous integration framework.

For enterprises that want to decouple the Swagger processing from their live servers, we have you covered too! We released an open source, “offline” version of WebSphere Liberty’s processor that works with a WAR input and produces the corresponding JSON or YAML Swagger definition. It supports the exact same three patterns that the “online” version supports. Check it out here. Note that you can use this to enable Swagger processing of your WebSphere Application Server traditional instances as well.

5 comments on"Deploying Swagger-enabled endpoints with WebSphere Liberty, IBM Cloud, and API Connect"

  1. Simon Helsen August 18, 2016

    Arthur, grt videos, but I am running in a funny problem after I deploy my application to Bluemix. The ibm/api/explorer endpoint is available, but when the Swagger UI tries to render itself, it complains with a message of this kind “Can’t read swagger JSON from https://.stage1.ng.bluemix.net/ibm/api/docs?compact=true

    When I manually check https://tiam.stage1.ng.bluemix.net/ibm/api/docs, it appears not to be available: Error 404: CWWKO1000E: There are no registered handlers that match the requested URL /ibm/api/docs.

    Then, when I check /ibm/api it only sends back this:

    “version”: 1,
    “roots”: [

    The logs are not showing anything suspicious. Note that everything works fine in my local deployment

    (If there is a better way to ask for support, let me know)

    • Arthur De Magalhaes August 19, 2016

      Hey Simon,

      As we found out yesterday, you must include the httpsPort attribute in your httpEndpoint element (in your server.xml), for example:


      • Arthur De Magalhaes August 19, 2016

        Formatting issues:

        <httpEndpoint host=”*” httpPort=”8010″ httpsPort=”8020″ id=”defaultHttpEndpoint”/>

  2. Arthur De Magalhaes August 03, 2016

    Hi Nihilson. Great question. Yes, the APIProvider interface is the perfect SPI for this environment. Just register a service that implements that interface, and you will get a chance to provide Swagger documentation (in either YAML or JSON format) into the aggregator.

    Please note that this is an SPI (not an API), which means it is only available if your OSGi bundle is part of a user of extended feature.

    In your Liberty installation, you’ll find the interface inside the jar wlp\dev\spi\ibm\com.ibm.websphere.appserver.spi.restHandler_x.jar

    The javadoc is inside the /javadoc folder in that parent directory, or online at http://www.ibm.com/support/knowledgecenter/SS7JFU_8.5.5/com.ibm.websphere.javadoc.liberty.doc/com.ibm.websphere.appserver.spi.restHandler_1.4-javadoc/com/ibm/wsspi/rest/api/discovery/APIProvider.html

  3. The demo and the sample application showing the hybrid pattern is very helpful. Good One !! Does the apiDiscovery-1.0 feature support only Web Applications for API discovery ? For non-web modules say a OSGi bundle fragment (.jar), will com.ibm.wsspi.rest.api.discovery.APIProvider Interface help ?

Join The Discussion

Your email address will not be published. Required fields are marked *