Spring REST: Springfox (Swagger)

diff --git a/SpringJava/REST/README b/SpringJava/REST/README
new file mode 100644 (file)
index 0000000..b8337ce
--- /dev/null
+++ b/SpringJava/REST/README
@@ -0,0 +1,9 @@
+
+Release:
+mvn clean install
+
+Documentation:
+mvn clean install -Dmaven.test.skip=true -Pdocumentation
+
+Javadoc and Sources:
+mvn dependency:sources && mvn dependency:resolve -Dclassifier=javadoc

diff --git a/SpringJava/REST/pom.xml b/SpringJava/REST/pom.xml
index 55c725b..73e0eb3 100644 (file)
--- a/SpringJava/REST/pom.xml
+++ b/SpringJava/REST/pom.xml
@@ -33,6 +33,59 @@
                                <activeByDefault>true</activeByDefault>
                        </activation>
                </profile>
+               <profile>
+                       <id>documentation</id>
+                       <properties>
+                               <environment.profile>documentation</environment.profile>
+                       </properties>
+                       <activation>
+                               <activeByDefault>false</activeByDefault>
+                       </activation>
+                       <dependencies>
+                               <!-- API documentation -->
+                               <dependency>
+                                       <groupId>io.springfox</groupId>
+                                       <artifactId>springfox-swagger2</artifactId>
+                                       <version>2.3.0</version>
+                               </dependency>
+                               <dependency>
+                                       <groupId>io.springfox</groupId>
+                                       <artifactId>springfox-swagger-ui</artifactId>
+                                       <version>2.3.0</version>
+                               </dependency>
+                       </dependencies>
+                       <build>
+                               <resources>
+                                       <resource>
+                                               <directory>${basedir}/src/doc/main/resources/</directory>
+                                               <includes>
+                                                       <include>**/*.*</include>
+                                               </includes>
+                                       </resource>
+                               </resources>
+                               <plugins>
+                                       <plugin>
+                                               <groupId>org.codehaus.mojo</groupId>
+                                               <artifactId>build-helper-maven-plugin</artifactId>
+                                               <version>1.10</version>
+                                               <executions>
+                                                       <execution>
+                                                               <id>add-source</id>
+                                                               <phase>process-sources</phase>
+                                                               <goals>
+                                                                       <goal>add-source</goal>
+                                                               </goals>
+                                                               <configuration>
+                                                                       <sources>
+                                                                               <source>src/doc/main/java/</source>
+                                                                       </sources>
+                                                               </configuration>
+                                                       </execution>
+                                               </executions>
+                                       </plugin>
+                               </plugins>
+                       </build>
+               </profile>
        </profiles>
 
        <dependencies>

diff --git a/SpringJava/REST/src/doc/main/java/de/spring/webservices/rest/doc/Swagger2Configuration.java b/SpringJava/REST/src/doc/main/java/de/spring/webservices/rest/doc/Swagger2Configuration.java
new file mode 100644 (file)
index 0000000..98821a6
--- /dev/null
+++ b/SpringJava/REST/src/doc/main/java/de/spring/webservices/rest/doc/Swagger2Configuration.java
@@ -0,0 +1,49 @@
+package de.spring.webservices.rest.doc;
+
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.web.bind.annotation.RequestMapping;
+
+import springfox.documentation.builders.ApiInfoBuilder;
+import springfox.documentation.builders.PathSelectors;
+import springfox.documentation.builders.RequestHandlerSelectors;
+import springfox.documentation.service.ApiInfo;
+import springfox.documentation.spi.DocumentationType;
+import springfox.documentation.spring.web.plugins.Docket;
+import springfox.documentation.swagger.web.UiConfiguration;
+import springfox.documentation.swagger2.annotations.EnableSwagger2;
+
+@Configuration
+@EnableSwagger2
+public class Swagger2Configuration {
+       private static final String DOCKET_ID = "web-services-spring-rest";
+       
+       @Bean
+       public Docket documentation() {
+               return new Docket(DocumentationType.SWAGGER_2)
+                               .groupName(DOCKET_ID)
+                               .select()
+                                       .apis(RequestHandlerSelectors.withMethodAnnotation(RequestMapping.class))
+                                       .paths(PathSelectors.any())
+                                       .build()
+                       .pathMapping("/")
+                       .useDefaultResponseMessages(false)
+                       .apiInfo(metadata());
+       }
+
+       @Bean
+       UiConfiguration uiConfig() {
+               return UiConfiguration.DEFAULT;
+       }
+
+       
+       private static ApiInfo metadata() {
+               return new ApiInfoBuilder()
+                               .title("gumartinm REST API")
+                               .description("Gustavo Martin Morcuende")
+                               .version("1.0-SNAPSHOT")
+                       .contact("gumartinm.name")
+                       .build();
+       }
+
+}

diff --git a/SpringJava/REST/src/doc/main/resources/spring-configuration/spring-config.xml b/SpringJava/REST/src/doc/main/resources/spring-configuration/spring-config.xml
new file mode 100644 (file)
index 0000000..5ca5917
--- /dev/null
+++ b/SpringJava/REST/src/doc/main/resources/spring-configuration/spring-config.xml
@@ -0,0 +1,27 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<beans xmlns="http://www.springframework.org/schema/beans"
+       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+       xmlns:context="http://www.springframework.org/schema/context"
+       xmlns:util="http://www.springframework.org/schema/util"
+       xsi:schemaLocation="http://www.springframework.org/schema/beans
+        http://www.springframework.org/schema/beans/spring-beans.xsd
+        http://www.springframework.org/schema/context
+        http://www.springframework.org/schema/context/spring-context.xsd
+        http://www.springframework.org/schema/util
+        http://www.springframework.org/schema/util/spring-util.xsd">
+
+       <!--
+       
+       Local deployment URLs:
+       
+       Swagger:
+       http://localhost:8080/web-services-spring-rest/spring-rest/v2/api-docs?group=web-services-spring-rest
+       
+       Swagger-UI:
+       http://localhost:8080/web-services-spring-rest/swagger-ui.html
+       
+       -->
+
+    <bean class="de.spring.webservices.rest.doc.Swagger2Configuration"/>
+
+</beans>

diff --git a/SpringJava/REST/src/main/java/de/spring/webservices/rest/CarController.java b/SpringJava/REST/src/main/java/de/spring/webservices/rest/CarController.java
index e566d91..ceafb42 100644 (file)
--- a/SpringJava/REST/src/main/java/de/spring/webservices/rest/CarController.java
+++ b/SpringJava/REST/src/main/java/de/spring/webservices/rest/CarController.java
@@ -20,6 +20,10 @@ import org.springframework.web.bind.annotation.RequestParam;
 import org.springframework.web.bind.annotation.ResponseStatus;
 import org.springframework.web.bind.annotation.RestController;
 
+//import io.swagger.annotations.ApiOperation;
+//import io.swagger.annotations.ApiResponse;
+//import io.swagger.annotations.ApiResponses;
+
 @RestController
 @RequestMapping("/api/cars/")
 public class CarController {
@@ -28,6 +32,12 @@ public class CarController {
     
     private final AtomicLong counter = new AtomicLong();
 
+//  Do I want to release with Swagger dependencies?
+//    @ApiOperation(value = "getCars", nickname = "getAllCars", response = Car.class)
+//    @ApiResponses({
+//        @ApiResponse(code =  404, message ="Not found"),
+//        @ApiResponse(code =  400, message ="Invalid input")
+//    })
     @RequestMapping(produces = { MediaType.APPLICATION_JSON_UTF8_VALUE }, method = RequestMethod.GET)
     @ResponseStatus(HttpStatus.OK)
     public List<Car> cars() {
@@ -39,6 +49,12 @@ public class CarController {
         return cars;
     }
 
+//  Do I want to release with Swagger dependencies?
+//  @ApiOperation(value = "getCar", nickname = "getsOneCar", response = Car.class)
+//  @ApiResponses({
+//      @ApiResponse(code =  404, message ="Not found"),
+//      @ApiResponse(code =  400, message ="Invalid input")
+//  })
     @RequestMapping(value = "{id}", produces = MediaType.APPLICATION_JSON_UTF8_VALUE, method = RequestMethod.GET)
     @ResponseStatus(HttpStatus.OK)
     public Car car(@RequestHeader(value = "MY_HEADER", required = false) String specialHeader,
@@ -74,6 +90,12 @@ public class CarController {
         return new Car(counter.incrementAndGet(), String.format(TEMPLATE, id));
     }
     
+//  Do I want to release with Swagger dependencies?
+//  @ApiOperation(value = "postCat", nickname = "createsNewCar", response = Car.class)
+//  @ApiResponses({
+//      @ApiResponse(code =  404, message ="Not found"),
+//      @ApiResponse(code =  400, message ="Invalid input")
+//  })
     @RequestMapping(consumes = MediaType.APPLICATION_JSON_UTF8_VALUE,
                produces = MediaType.APPLICATION_JSON_UTF8_VALUE, method = RequestMethod.POST)
     public ResponseEntity<Car> create(@RequestBody Car car) {

diff --git a/SpringJava/REST/src/main/resources/spring-configuration/mvc/rest/rest-config.xml b/SpringJava/REST/src/main/resources/spring-configuration/mvc/rest/rest-config.xml
index 77232ab..bed7947 100644 (file)
--- a/SpringJava/REST/src/main/resources/spring-configuration/mvc/rest/rest-config.xml
+++ b/SpringJava/REST/src/main/resources/spring-configuration/mvc/rest/rest-config.xml
@@ -68,5 +68,5 @@
        <bean id="handlerMapping" class="org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerMapping"/>
 
        <mvc:default-servlet-handler />
-        
+       
 </beans>