The definition of our API will include a single endpoint /notes which allows us to execute GET, POST, and DELETE requests. This task will be performed via the Swagger Editor, where we can depict the API in YAML format while obtaining the preview of the documentation that will be generated afterwards. We will create an interface for a small note manager which will include the classic reading and writing operations. To begin with, let’s define the API that will be used in our example. The best way of seeing how to use Swagger in our JAX-RS modules is with an example, so let’s do an example :) Defining an example API This file is used to generate both the documentation and code to serve our REST API and will then provide the DTOs used in our Liferay backend. You can form a clear picture of what this is all about: With Swagger, we can abstract the logic of the API implementation on simple file that holds an OpenAPI definition. With Swagger Codegen one can generate the code both as client and server in over 50 programming languages, and with SwaggerUI, we can test and see the documentation for the designed API. With Swagger Editor and the OpenAPI specification, we can design and describe the API we are about to build. When we talk about Swagger we are referring to a framework used for designing, documenting and building REST APIs.

OK, and what is this thing called Swagger? It is closely linked to the new JS frameworks which are flooding the modern Internet these days: such an accepted specification streamlines the development of the APIs that of late consume the applications developed on Angular, React or even MetalJS. The appearance of JAX-RS in Liferay DXP is no accident. This specification has several implementations including Apache CXF, which is what we will find in Liferay. JAX-RS is a JEE specification based on annotations such as: or which simplify REST API development. In this article, we are going to convince you to take the plunge with this new technology, showing how its combination with Swagger and the OpenAPI specification can help us to quickly build robust REST API.

With the arrival of Liferay DXP and JAX-RS services, we discovered a whole new world beyond JSON-WS and Service Builder.

Swagger editor json demo