Document Enum in Swagger

1. Overview

In this tutorial, we’ll learn how to document enum in Swagger using the swagger-maven-plugin and verify the generated JSON document in the swagger editor.

2. What Is Swagger?

A Swagger is an open-source tool for defining rest-based APIs. In today’s world, most organizations are moving towards microservices and API first approach. Swagger comes in very handy for designing as well as documenting APIs. It also provides various tools like Swagger Editor, Swagger UI, and Swagger CodeGen to assist API development.

Also, Swagger is an implementation of OpenAPI specifications or OAS, which defines the set of standards for rest API development; consequently, it helps organizations across the globe to standardize the process of writing APIs.

The JSON file generated by our application will also follow the OpenAPI specifications.

Let’s try to understand the importance of Enum in Swagger. Some APIs need the user to stick with a specific set of pre-defined values. These pre-defined constant values are called enum. Similarly, when Swagger exposes APIs, we want to ensure that the user selects a value from this pre-defined set rather than free text. In other words, we need to document enums in our swagger.json file so that the user is aware of the possible values.

3. Implementation

Let’s take an example of a REST API and jump to the implementation. We’ll implement a POST API to hire employees for an organization for specific roles. However, a role can only be one of the following: Engineer, Clerk, Driver, or Janitor.

We’ll create an enum named Role with all the possible values of employee role and create a class Employee having a role as one of its properties. Let’s have a look at the UML diagram for a better understanding of the classes and their relationship:

To document this in Swagger, firstly, we’ll import and configure the swagger-maven-plugin in our application. Secondly, we’ll add required annotations to our code, and finally, we’ll build the project and verify the generated swagger document or swagger.json in the swagger editor.

3.1. Import and Configure Plugin

We’re going to use swagger-maven-plugin, and we need to add it as a dependency to the pom.xml of our application:

<dependency>
    <groupId>com.github.kongchen</groupId>
    <artifactId>swagger-maven-plugin</artifactId>
    <version>3.1.1</version>
</dependency>

Also, to configure and enable this plugin, we’ll add it under the plugins section of the pom.xml:

• locations: This tag specifies the packages or classes containing @Api separated by a semi-colon
• info: This tag provides metadata for the APIs. Swagger-ui uses this data to display information
• swaggerDirectory: This tag defines the path of the swagger.json file

<plugin>
    <groupId>com.github.kongchen</groupId>
    <artifactId>swagger-maven-plugin</artifactId>
    <version>3.1.1</version>
    <configuration>
        <apiSources>
            <apiSource>
                <springmvc>false</springmvc>
                <locations>com.baeldung.swaggerenums.controller</locations>
                <schemes>http,https</schemes>
                <host>baeldung.com</host>
                <basePath>/api</basePath>
                <info>
                    <title>Baeldung - Document Enum</title>
                    <version>v1</version>
                    <description>This is a Baeldung Document Enum Sample Code</description>
                    <contact>
                        <email>[email protected]</email>
                        <name>Test</name>
                    </contact>
                    <license>
                        <url>https://www.apache.org/licenses/LICENSE-2.0.html</url>
                        <name>Apache 2.0</name>
                    </license>
                </info>
                <swaggerDirectory>generated/swagger-ui</swaggerDirectory>
            </apiSource>
        </apiSources>
    </configuration>
    <executions>
        <execution>
            <phase>compile</phase>
            <goals>
                <goal>generate</goal>
            </goals>
        </execution>
     </executions>
 </plugin>

3.2. Documenting an Enum

In order to document an enum in Swagger, we need to declare the models using annotation @ApiModel.

In this example, we created an enum Role with four possible values – Engineer, Clerk, Driver, and Janitor. As we need to document this enum, we’ll add @ApiModel to the enum Role. In other words, this will let the Swagger know about the presence of the model. In the Employee class, we’ll annotate the Employee with @ApiModel and Role with @ApiModelProperty.

Our Employee, Role, and HireController will look like:

@ApiModel
public class Employee {
    @ApiModelProperty
    public Role role;

   // standard setters and getters
}

@ApiModel
public enum Role {
    Engineer, Clerk, Driver, Janitor;
}

Next, we’ll create an API with @Path as “/hire” and use the Employee model as an input parameter to the hireEmployee method. We have to add @Api to our HireController so that the swagger-maven-plugin is aware and should consider it for documenting:

@Api
@Path(value="/hire")
@Produces({"application/json"})
public class HireController {

    @POST
    @ApiOperation(value = "This method is used to hire employee with a specific role")
    public String hireEmployee(@ApiParam(value = "role", required = true) Employee employee) {
        return String.format("Hired for role: %s", employee.role.name());
    }
}

3.3. Generating the Swagger Document

To build our project and generate a swagger document, run the following command:

mvn clean install

Once built, the plugin will generate the swagger.json file at generated/swagger-ui or at the location configured in the plugin. Looking under the definitions, we’ll see the enum Role documented inside the employee properties with all its possible values.

"definitions" : {
  "Employee" : {
    "type" : "object",
    "properties" : {
      "role" : {
        "type" : "string",
        "enum" : [ "Engineer", "Clerk", "Driver", "Janitor" ]
      }
    }
  }
}

Now, we’ll visualize the generated JSON using the online swagger editor and look for the enum Role:

4. Conclusion

In this tutorial, we discussed what Swagger is and learned about the OpenAPI specification and its importance in API development for organizations. Also, we created and documented our sample API containing enum using the swagger-maven-plugin. Finally, to validate the output, we used the swagger editor to visualize the generated JSON document.