BAEL-5326 - Documenting Enum in swagger using swagger maven plugin (#11811)

* BAEL-5326 - Documenting Enum in swagger using swagger maven plugin

* BAEL-5326 - Documenting Enum in swagger using swagger maven plugin
Changes:
HireControllerTest -> HireControllerUnitTest
hireEmployee_RoleEngineer_ReturnsRoleString -> givenRoleEngineer_whenHireEmployee_thenReturnsRoleInString

* Moved to module: spring-boot-swagger

spring-boot-modules/spring-boot-swagger/generated/swagger-ui/swagger.json

@@ -0,0 +1,57 @@
+{
+  "swagger" : "2.0",
+  "info" : {
+    "description" : "This is a Baeldung Document Enum Sample Code",
+    "version" : "v1",
+    "title" : "Baeldung - Document Enum",
+    "contact" : {
+      "name" : "Parikshit Murria",
+      "email" : "pmurria@baeldung.com"
+    },
+    "license" : {
+      "name" : "Apache 2.0",
+      "url" : "https://www.apache.org/licenses/LICENSE-2.0.html"
+    }
+  },
+  "host" : "baeldung.com",
+  "basePath" : "/api",
+  "schemes" : [ "http", "https" ],
+  "paths" : {
+    "/hire" : {
+      "post" : {
+        "summary" : "This method is used to hire employee with a specific role",
+        "description" : "",
+        "operationId" : "hireEmployee",
+        "produces" : [ "application/json" ],
+        "parameters" : [ {
+          "in" : "body",
+          "name" : "body",
+          "description" : "role",
+          "required" : true,
+          "schema" : {
+            "$ref" : "#/definitions/Employee"
+          }
+        } ],
+        "responses" : {
+          "200" : {
+            "description" : "successful operation",
+            "schema" : {
+              "type" : "string"
+            }
+          }
+        }
+      }
+    }
+  },
+  "definitions" : {
+    "Employee" : {
+      "type" : "object",
+      "properties" : {
+        "role" : {
+          "type" : "string",
+          "enum" : [ "Engineer", "Clerk", "Driver", "Janitor" ]
+        }
+      }
+    }
+  }
+}

spring-boot-modules/spring-boot-swagger/pom.xml

@@ -25,6 +25,11 @@
             <artifactId>springfox-boot-starter</artifactId>
             <version>${springfox.version}</version>
         </dependency>
+        <dependency>
+            <groupId>com.github.kongchen</groupId>
+            <artifactId>swagger-maven-plugin</artifactId>
+            <version>${swagger-maven-plugin.version}</version>
+        </dependency>
     </dependencies>
 
     <build>
@@ -33,11 +38,50 @@
                 <groupId>org.springframework.boot</groupId>
                 <artifactId>spring-boot-maven-plugin</artifactId>
             </plugin>
+            <plugin>
+                <groupId>com.github.kongchen</groupId>
+                <artifactId>swagger-maven-plugin</artifactId>
+                <version>${swagger-maven-plugin.version}</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>pmurria@baeldung.com</email>
+                                    <name>Parikshit Murria</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>
         </plugins>
     </build>
 
     <properties>
         <springfox.version>3.0.0</springfox.version>
+        <swagger-maven-plugin.version>3.1.1</swagger-maven-plugin.version>
     </properties>
 
 </project>

spring-boot-modules/spring-boot-swagger/src/main/java/com/baeldung/swaggerenums/SwaggerEnumsApplication.java

@@ -0,0 +1,13 @@
+package com.baeldung.swaggerenums;
+
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+
+@SpringBootApplication
+public class SwaggerEnumsApplication {
+
+    public static void main(String[] args) {
+        SpringApplication.run(SwaggerEnumsApplication.class, args);
+    }
+
+}

spring-boot-modules/spring-boot-swagger/src/main/java/com/baeldung/swaggerenums/controller/HireController.java

@@ -0,0 +1,22 @@
+package com.baeldung.swaggerenums.controller;
+
+import com.baeldung.swaggerenums.model.Employee;
+import io.swagger.annotations.Api;
+import io.swagger.annotations.ApiOperation;
+import io.swagger.annotations.ApiParam;
+
+import javax.ws.rs.POST;
+import javax.ws.rs.Path;
+import javax.ws.rs.Produces;
+
+@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());
+    }
+}

spring-boot-modules/spring-boot-swagger/src/main/java/com/baeldung/swaggerenums/model/Employee.java

@@ -0,0 +1,17 @@
+package com.baeldung.swaggerenums.model;
+
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
+
+@ApiModel
+public class Employee {
+    @ApiModelProperty
+    public Role role;
+
+    public Role getRole() {
+        return role;
+    }
+    public void setRole(Role role) {
+        this.role = role;
+    }
+}

spring-boot-modules/spring-boot-swagger/src/main/java/com/baeldung/swaggerenums/model/Role.java

@@ -0,0 +1,8 @@
+package com.baeldung.swaggerenums.model;
+
+import io.swagger.annotations.ApiModel;
+
+@ApiModel
+public enum Role {
+    Engineer, Clerk, Driver, Janitor;
+}

spring-boot-modules/spring-boot-swagger/src/test/java/com/baeldung/swaggerenums/controller/HireControllerUnitTest.java

@@ -0,0 +1,25 @@
+package com.baeldung.swaggerenums.controller;
+
+import com.baeldung.swaggerenums.model.Employee;
+import com.baeldung.swaggerenums.model.Role;
+import org.junit.Assert;
+import org.junit.Test;
+
+public class HireControllerUnitTest {
+
+    @Test
+    public void givenRoleEngineer_whenHireEmployee_thenReturnsRoleInString() {
+        //Arrange
+        Role testRole = Role.Engineer;
+        Employee employee = new Employee();
+        employee.setRole(testRole);
+
+        //Act
+        HireController hireController = new HireController();
+        String response = hireController.hireEmployee(employee);
+
+        //Assert
+        Assert.assertEquals(String.format("Hired for role: %s", testRole),
+                response);
+    }
+}