Merge pull request #17 from AdamZink/develop

Part 4 to master

Author: AdamZink

README.md

@@ -13,3 +13,4 @@ Tutorials are available to explain the steps on [Medium](https://medium.com/@ada
 * [Part 1 - Create a Spring Boot application with Spring Initializr](https://medium.com/@adamzink/creating-an-api-with-spring-boot-and-mysql-part-1-4c5544a2a202)
 * [Part 2 - Create the first API endpoint to POST a User](https://medium.com/@adamzink/creating-an-api-with-spring-boot-and-mysql-part-2-1b3f5740c7bf)
 * [Part 3 - Create more API endpoints to GET, PUT, and DELETE Users](https://medium.com/@adamzink/creating-an-api-with-spring-boot-and-mysql-part-3-f1b5ef9334c0)
+* [Part 4 - Add API documentation with Swagger](https://medium.com/@adamzink/creating-an-api-with-spring-boot-and-mysql-part-4-d39edbe87b53)

pom.xml

@@ -56,6 +56,19 @@
 			<artifactId>spring-boot-starter-test</artifactId>
 			<scope>test</scope>
 		</dependency>
+
+		<!-- Added for Part 4 -->
+		<dependency>
+			<groupId>io.springfox</groupId>
+			<artifactId>springfox-swagger2</artifactId>
+			<version>2.9.2</version>
+		</dependency>
+		<dependency>
+			<groupId>io.springfox</groupId>
+			<artifactId>springfox-swagger-ui</artifactId>
+			<version>2.9.2</version>
+		</dependency>
+
 	</dependencies>
 
 	<build>
@@ -64,6 +77,34 @@
 				<groupId>org.springframework.boot</groupId>
 				<artifactId>spring-boot-maven-plugin</artifactId>
 			</plugin>
+			<plugin>
+				<groupId>com.github.kongchen</groupId>
+				<artifactId>swagger-maven-plugin</artifactId>
+				<configuration>
+					<apiSources>
+						<apiSource>
+							<locations>
+								<location>com.github.adamzink.springbootmysqldemo.resource</location>
+							</locations>
+							<basePath>/api</basePath>
+							<swaggerDirectory>${project.build.directory}/classes/swagger</swaggerDirectory>
+							<swaggerFileName>swagger</swaggerFileName>
+							<info>
+								<title>Spring Boot MySQL Demo</title>
+								<version>1.0</version>
+							</info>
+						</apiSource>
+					</apiSources>
+				</configuration>
+				<executions>
+					<execution>
+						<phase>compile</phase>
+						<goals>
+							<goal>generate</goal>
+						</goals>
+					</execution>
+				</executions>
+			</plugin>
 		</plugins>
 	</build>
 

src/main/java/com/github/adamzink/springbootmysqldemo/JerseyConfiguration.java

@@ -4,6 +4,9 @@
 import org.glassfish.jersey.server.ResourceConfig;
 import org.springframework.stereotype.Component;
 
+import javax.ws.rs.ApplicationPath;
+
+@ApplicationPath("/api")
 @Component
 public class JerseyConfiguration extends ResourceConfig {
 

src/main/java/com/github/adamzink/springbootmysqldemo/config/SwaggerConfiguration.java

@@ -0,0 +1,36 @@
+package com.github.adamzink.springbootmysqldemo.config;
+
+import org.springframework.context.annotation.Configuration;
+import org.springframework.context.annotation.Primary;
+import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
+import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
+import springfox.documentation.swagger.web.SwaggerResource;
+import springfox.documentation.swagger.web.SwaggerResourcesProvider;
+import springfox.documentation.swagger2.annotations.EnableSwagger2;
+
+import java.util.Collections;
+import java.util.List;
+
+@Configuration
+@EnableSwagger2
+@Primary
+public class SwaggerConfiguration implements SwaggerResourcesProvider, WebMvcConfigurer {
+
+    @Override
+    public List<SwaggerResource> get() {
+        SwaggerResource swaggerResource = new SwaggerResource();
+        swaggerResource.setLocation("/swagger/swagger.json");
+        swaggerResource.setName("Spring Boot MySQL Demo API");
+
+        return Collections.singletonList(swaggerResource);
+    }
+
+    @Override
+    public void addResourceHandlers(ResourceHandlerRegistry registry) {
+        registry.addResourceHandler("swagger-ui.html")
+                .addResourceLocations("classpath:/META-INF/resources/");
+
+        registry.addResourceHandler("/swagger/**")
+                .addResourceLocations("classpath:/swagger/");
+    }
+}

src/main/java/com/github/adamzink/springbootmysqldemo/resource/UserResource.java

@@ -3,6 +3,7 @@
 import com.github.adamzink.springbootmysqldemo.model.client.User;
 import com.github.adamzink.springbootmysqldemo.model.client.UserRequest;
 import com.github.adamzink.springbootmysqldemo.service.UserService;
+import io.swagger.annotations.*;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.stereotype.Component;
 
@@ -11,6 +12,7 @@
 import java.util.Collection;
 
 @Path("/users")
+@Api(value = "User", description = "Resource for getting and modifying Users")
 @Component
 public class UserResource {
 
@@ -19,28 +21,48 @@ public class UserResource {
 
     @GET
     @Produces(MediaType.APPLICATION_JSON)
+    @ApiOperation(value = "Get all Users",
+            response = User.class,
+            responseContainer = "List")
     public Collection<User> getAll() {
         return userService.getAll();
     }
 
     @POST
     @Consumes(MediaType.APPLICATION_JSON)
     @Produces(MediaType.APPLICATION_JSON)
-    public User save(final UserRequest userRequest) {
+    @ApiOperation(value = "Create a User",
+            response = User.class)
+    @ApiResponses(value = {
+            @ApiResponse(code = 400, message = "Bad request format")})
+    public User save(
+            @ApiParam(value = "User to be created", required = true) final UserRequest userRequest) {
         return userService.save(userRequest);
     }
 
     @PUT
     @Path("{id}")
     @Consumes(MediaType.APPLICATION_JSON)
     @Produces(MediaType.APPLICATION_JSON)
-    public User update(@PathParam("id") final Long id, final UserRequest userRequest) {
+    @ApiOperation(value = "Update a User",
+            response = User.class)
+    @ApiResponses(value = {
+            @ApiResponse(code = 400, message = "Bad request format"),
+            @ApiResponse(code = 404, message = "User not found")})
+    public User update(
+            @ApiParam(value = "User id to update", required = true) @PathParam("id") final Long id,
+            @ApiParam(value = "User details to be updated", required = true) final UserRequest userRequest) {
         return userService.update(id, userRequest);
     }
 
     @DELETE
     @Path("{id}")
-    public void delete(@PathParam("id") final Long id) {
+    @ApiOperation(value = "Delete a User")
+    @ApiResponses(value = {
+            @ApiResponse(code = 204, message = "User deleted successfully"),
+            @ApiResponse(code = 404, message = "User not found")})
+    public void delete(
+            @ApiParam(value = "User id to delete", required = true) @PathParam("id") final Long id) {
         userService.delete(id);
     }
 

src/main/java/com/github/adamzink/springbootmysqldemo/service/UserService.java

@@ -9,6 +9,8 @@
 import org.springframework.stereotype.Service;
 import org.springframework.transaction.annotation.Transactional;
 
+import javax.ws.rs.BadRequestException;
+import javax.ws.rs.NotFoundException;
 import java.util.Collection;
 import java.util.Date;
 
@@ -27,26 +29,38 @@ public Collection<User> getAll() {
     }
 
     public User save(final UserRequest userRequest) {
-        UserModel userModel = userConverter.requestToModel(userRequest);
+        UserModel userModel = getValidatedRequestToModel(userRequest);
 
         userModel.setAddTs(new Date());
 
         return userConverter.modelToResponse(userRepository.save(userModel));
     }
 
     public User update(final Long id, final UserRequest userRequest) {
-        UserModel fromRequest = userConverter.requestToModel(userRequest);
+        UserModel toSave = userRepository.findById(id).orElseThrow(NotFoundException::new);
+
+        UserModel fromRequest = getValidatedRequestToModel(userRequest);
 
-        UserModel toSave = userRepository.getOne(id);
         toSave.setFirstName(fromRequest.getFirstName());
         toSave.setLastName(fromRequest.getLastName());
 
         return userConverter.modelToResponse(userRepository.save(toSave));
     }
 
     public void delete(final Long id) {
+        userRepository.findById(id).orElseThrow(NotFoundException::new);
         userRepository.deleteById(id);
     }
 
+    private UserModel getValidatedRequestToModel(final UserRequest userRequest) {
+        UserModel model = userConverter.requestToModel(userRequest);
+
+        if (model.getFirstName() == null || model.getLastName() == null) {
+            throw new BadRequestException();
+        }
+
+        return model;
+    }
+
 }
 

src/main/resources/application.properties

@@ -6,6 +6,3 @@ spring.datasource.driver-class-name=com.mysql.jdbc.Driver
 
 # Flyway properties
 spring.flyway.locations=classpath:db/mysql/migration
-
-# Path properties
-server.servlet.contextPath=/api