Get More Transparency on Your Microservices API With OpenAPI

DZone 's Guide to

Get More Transparency on Your Microservices API With OpenAPI

We'll create a small Java API that will handle all Deploy-Fridays episodes and store it on MongoDB and then test it with Postman.

· Java Zone ·
Free Resource

Every Friday, Platform.sh has a nice tech discussion about several discussions, such as Jakarta EE, Payara, Quarkus, and so on (To check the calendar you can click here). On Episode number 15 there was a great discussion about Open API and Postman. That's worth watching if you don't yet.

First, let's start with Open API definition, from the website it says:

The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined, a consumer can understand and interact with the remote service with a minimal amount of implementation logic.

Hello World Open API With Postman

To absorb that knowledge and practice what we learned from this episode, let's create a Hello world Open API and then test it with Postman. We'll create a small Java API that will handle all Deploy-Fridays episodes and store it on MongoDB. Why do we want to use MongoDB? Just because we're hipsters!!

We're going to be using Eclipse MicroProfile. This will make our life easier when we want to create a microservices application. In this tutorial, we'll use Helidon version 2.0. To integrate with a NoSQL database let's use Jakarta NoSQL.

Eclipse MicroProfile has a subproject to integrate with Open API that's annotation-driven.




A container for multiple responses from an API operation. This annotation is optional, but it can be helpful to organize a method with multiple responses.


Describes a single response from an API operation.


Provides a schema and examples for a particular media type.


Defines the input and output data types.


Describes a single API operation on a path.


Describes a single operation parameter.

Let's start with the entities; remember that those entities will also be the data inputs, so we'll define them as a schema.

As you can see in the code, beyond the Eclipse MicroProfile Open API annotations, there are also the Jakarta NoSQL entities annotations and JSON Binding to check the fields instead of methods.


After creating the entity, the next step to create the resource. As the usual JAX-RS annotation to define the path and the HTTP verbs such as GET, POST, and DELETE, there are also the Open API annotations.


The code is ready, to run locally let's use Docker with the command below:


The application is ready, and with MongoDB instance running, you can execute the application:


When the application is running, you can access the URL http://localhost:8080/openapi/ to get the open API result.

Let's go to the Postman to test your API; the first step is to import the API from the URL that we already showed.

Let's go to the Postman to test your API. The first step is to install the application itself where it has support for Linux, Windows or Mac OS. When we installed the Postman application, the next step is to import the API from the Open API URL.

It works like magic, don't forget to set the variables inside Postman.

Cloud: To Infinity and Beyond With Platform.sh

The application is ready to go, and you can run the application.  The next step is to move to the cloud with Platform.sh.

 To move your application to the cloud, briefly, you need three files:

 One to define the routes


One file to define the services that you need in your application.

To point out, you don't need to worry to handle it. Platform.sh will be the infrastructure for you.



  type: mongodb:3.6
  disk: 1024

The last file is to configure the application, basically, you'll teach how to build and execute your application to Platform.sh. In this sample, we'll create a Java 11 container,  build with a maven command, and start the application from an uberjar.


As you can see, we set the CREDENTIAL environment. The goal is to overwrite the database credentials on the cloud, so we can have a configuration to run locally and another one to run in the cloud with Platform.sh.


The application is now ready, so it’s time to move it to the cloud with Platform.sh using the following steps:

  • Create a new free trial account.

  • Sign up with a new user and password, or login using a current GitHub, Bitbucket, or Google account. If you use a third-party login, you’ll be able to set a password for your Platform.sh account later.

  • Select the region of the world where your site should live.

  • Select the blank template.

You have the option to either integrate to GitHub, GitLab, or Platform.sh will provide it to you. Finally, push to the remote repository.

The example is ready and in a GitHub repository.

That is it; we finished a tutorial about how to integrate and connect a Java application with Open API and test with Postman. Stay tuned to the next Deploy Friday episodes.

helidon, java, microprofile, openapi, postman

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}