Document Enum in Swagger – Swagger中的文档枚举

最后修改: 2022年 2月 19日

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?

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.

Swagger是一个开源的工具,用于定义基于rest的API。在当今世界,大多数组织都在向微服务和API优先的方法发展。Swagger在设计和记录API时非常方便。它还提供各种工具,如Swagger编辑器、Swagger UI和Swagger CodeGen,以协助API开发。

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.

让我们举一个REST API的例子,然后跳到实现。我们将实现一个POST API,为一个组织雇用特定角色的员工。然而,一个角色只能是以下的一个。工程师职员司机、或清洁工

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:


UML Diagram HireController

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:



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
                    <title>Baeldung - Document Enum</title>
                    <description>This is a Baeldung Document Enum Sample Code</description>
                        <name>Apache 2.0</name>

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:


public class Employee {
    public Role role;

   // standard setters and getters
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:


public class HireController {

    @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",;

3.3. Generating the Swagger Document


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


mvn clean install

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:


Swagger Editor

Swagger Editor

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.


This implementation can be found over on GitHub.