Everyday we see new APIs being exposed by products – some are for administrative purposes, others for tapping into business assets, the list goes on – and since these APIs are contracts (written as OpenAPI documents) between the producers and consumers, they must be designed correctly from the start.

By far the most popular tool available today for collaborative design of OpenAPI documents is SwaggerHub. It contains over 25 000 public APIs in its repository, plus many thousands of internal repositories that individuals and companies maintain. SwaggerHub allows users to remotely collaborate with each other on the design of an API, including any domains that they may use across a set of APIs.

In this article we’ll go through the design process in SwaggerHub and demonstrate how you can quickly add an integration layer with GitHub which generates the necessary JAX-RS 2.0 code and triggers a devOps pipeline in IBM Cloud that builds and deploys the application. We will also demonstrate SwaggerHub’s new integration with API Connect, which adds another layer of API management and security to your application.

Here’s an architectural view of what we’re building:


You can start by creating a free account at swaggerhub.com. Once inside, click on the screen button with a plus sign and select Create New API:

You have the option of building an API from scratch or starting from an existing template. For the purposes of this article, we will use our existing Inventory API (on GitHub).

You’ll notice that SwaggerHub provides a real-time API editor, rendering the document into a UI form. This allows for very fast development of your API because you receive feedback from errors and warnings immediately, and you can visualize the API and its operations.

Here’s a screenshot of our API:

You can invite more collaborators to your API by clicking on the share icon in the top-right corner:
This feature allows contributors from any part of the world to view and edit (depending on the enabled role) your API!

Code generation into GitHub

The editor in SwaggerHub has the same code generation capability as the Open Source Swagger Codegen project. We will use this feature to generate the JAX-RS 2.0 skeleton of our API, including all the models and entry endpoints. We can set this up by adding a new GitHub integration by clicking the integration icon:

You can pick any GitHub repository that you have access to. For this article, we’re using this GitHub repo: https://github.com/microservices-api/java-rest-inventory

For the Generated API Code option, pick jaxrs-spec.

Now, each time you want to push a generated JAX-RS 2.0 version of your API, you simply run this integration by clicking on the integration icon and then on the icon that resembles a play button:

You can see an example of what gets generated at https://github.com/microservices-api/java-rest-inventory/tree/master/jaxrs-spec/src/gen/java/io/swagger

Before we’re ready to hook in our DevOps pipeline, we need to add just a few more artifacts to our GitHub repository. The first thing is the business logic, which will augment the generated skeleton. There are many techniques to achieve this (such as adding a Controller and provides the logic for each of the generated operations) but, for this sample, we will simply overlay the main API endpoint with a very basic implementation, which you can copy from this sample class on GitHub.

The only other required artifact is a server.xml for Liberty. This enables the features that your application needs plus the apiDiscovery-1.0 feature to view your API. You can copy this sample server.xml on GitHub.

Optionally, if you want to customize the look-and-feel of Liberty’s Swagger UI, you could add a customized JSON snippet and CSS, such as this sample customization on GitHub.

IBM Cloud DevOps toolchain

Now we’re ready to set up a (free!) DevOps pipeline that will listen for changes in GitHub and start our chain accordingly. Log into IBM Cloud, navigate into the DevOps category of the dashboard and pick the Continuous Delivery service:

Pick a name and click the Create button. On the next panel, click Start Here from the section that says “Start with a pipeline”, then leave Cloud Foundry template selected and enter names of your choice for the pipeline, application, and toolchain.

For this article, the source location we will use is our GitHub repository located at https://github.com/microservices-api/java-rest-inventory.

Once that is completed, you can click on the delivery pipeline icon to configure the pipeline. Now we’re ready to configure our pipeline! You’ll notice that two stages have been added for you: Build and Deploy.

Start by clicking on the configuration icon of the build stage:

The input is already set to our Git repository, so we’ll go into the Jobs tab. For this article we’ll set Maven as the Builder Type and the following commands:

mv ../pom.xml pom.xml
mv ../web/InventoryApi.java src/gen/java/io/swagger/api/InventoryApi.java
mvn -B package
mv ../web/defaultServer $ARCHIVE_DIR/defaultServer
mv $ARCHIVE_DIR/swagger-jaxrs-server-1.0.0.war $ARCHIVE_DIR/defaultServer/dropins/api.war

Here’s a screenshot of the configuration:

Clicking Save will bring you back into the pipeline view, where you can click the Start icon to initiate the build:

We can move into the configuration of the Deploy stage. We’ll leave the default input, which is the previous stage (build), so we can click on the Jobs tab of this stage.

For this article, we’ll set Cloud Foundry as the Deployer Type but you can use other types too, such as the IBM Container Services. As we’re deploying a Java application, it will use the WebSphere Liberty buildpack. Pick appropriate values for Target, Organization, Space and Application Name fields.

We’re using the following deployment script:

cf push "${CF_APP}" -p defaultServer -b liberty-for-java -health-check-type none

Now your deploy stage is ready to run! You can either kick it off manually or commit a new change to GitHub (from SwaggerHub) and watch the DevOps toolchain work! When the deployment stage completes, you should see a similar image as this:

Notice the app URL (ending with mybluemix.net). If you used the exact same server.xml (with the customization JSON/CSS) as we did, then you can navigate into <appURL>/cloud/explorer. Otherwise, you can navigate into the default Swagger UI URL, at <appURL>/api/explorer:

The image above illustrates the API you designed with SwaggerHub, which has been built from the code generated into GitHub, deployed into Cloud Foundry / IBM Cloud (using the WebSphere Liberty buildpack), and rendered using WebSphere Liberty’s native Swagger UI! You can use this Swagger UI to try out each operation of your API and test its behaviour.

API Connect

The final step is to add an API management layer on top of our cloud-native API. Our management layer will be the API Connect (APIC) Service from IBM Cloud. If you don’t already have an API Connect service you can quickly create one (for free!) by picking API Connect from the APIs section of the IBM Cloud catalog and choosing the Essentials license.

We now have a few options at this stage:

  • Import Liberty’s optimized `GET /ibm/api/docs/apiconnect` into APIC’s draft section
  • Push Liberty’s API straight into an APIC catalog using the `POST /ibm/api/docs/apiconnect` endpoint
  • Push the API definition from SwaggerHub into APIC’s draft section

Since we already have a video and a tutorial covering the first two options, let’s focus on the SwaggerHub integration with API Connect.

Similar to the GitHub integration point that you set up previously, in your SwaggerHub API panel pick the API Connect integration:

Simply add your IBM ID credentials (notice to IBMers: this is your IBM ID, not the federated intranet ID) and SwaggerHub will connect to the IBM Cloud API Connect service to fetch your API organization information. That’s all the setup you need to do!

Now each time you wish to push your API into API Connect, simply click on the execution icon:

You’ll notice that this API is now available in API Connect’s draft section, ready for an API administrator to place it inside an appropriate product and publish it into a catalog:

Congratulations! You have now set up an environment where you collaboratively design your APIs (SwaggerHub), while automatically producing skeleton implementations (GitHub integration and JAX-RS Generation), which kick off a DevOps pipeline (IBM Cloud toolchain) that builds and deploys the application (WebSphere Liberty buildpack) with an added API management layer (API Connect integration) on top of it!

Join The Discussion

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