Adding Swagger to Quarkus

Table of contents

Reading Time: 2 minutes

Introduction

Open API or Swagger specification is the factual standard for creating REST APIs. Almost every developer expects to see some Swagger documentation when working with APIs or doing integration. In this blog, we will go through how to add Swagger to Quarkus application

Add Open API dependency

Here we need to add the quarkus-small rye-open API to the project, It will generate an OpenAPI dynamic schema and also has a built-in Swagger UI.

<dependencies>
  <dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-smallrye-openapi</artifactId>
  </dependency>
</dependencies>

Add configuration Class

We don’t necessarily need to have this file, but it’s highly recommended. It contains annotations that provide information about the API’s purpose, maintainer, licensing, etc. Note that to make the annotations work, the CustomApi.java file should extend Application from javax.ws.rs.core.Application.

Enable Swagger UI

To change the path, add this configuration

quarkus.smallrye-openapi.path=/swagger

quarkus.swagger-ui.always-include=true

After that, Swagger UI is accessible at /swagger-ui.

Override this parameter to provide a custom path

quarkus.swagger-ui.path=/swagger-ui.html

Document the APIs

We will create a Student bean and a StudentResource REST resource

Swagger UI

In any project when developers build APIs, developers want to test them easily and fast. So, Swagger UI is a great tool permitting you to visualize and interact with your APIs in a properly documented form. The Swagger UI produces our APIs in a proper documented form which is automatically generated from your OpenAPI specification.

Conclusion

In this blog, we create a straightforward REST application to demonstrate how fast you can expose your API specification and benefit from a user interface to test it. In Quarkus swagger is based on smart defaults and the dependencies available on the classpath. Anyone can adjust all defaults and add their own parameters to the configuration file.