Add example swagger usage

.gitignore

@@ -2,3 +2,6 @@
 *.iml
 target
 dependency-reduced-pom.xml
+/.classpath
+/.project
+/.settings/

README.md

@@ -12,7 +12,11 @@ $ mvn install
 $ java -jar target/gwizard-example-1.0-SNAPSHOT.jar test.yml
 ```
 
-The most exciting endpoint is probably: http://localhost:8081/fun/headers
+The most exciting endpoints are probably: 
+
+* http://localhost:8081/fun/headers
+* http://localhost:8081/swagger.json
+* http://localhost:8081/swagger.yaml
 
 (Note that test.yml changes the port from the default of 8080, just to demonstrate)
 

pom.xml

@@ -71,6 +71,11 @@
 			<artifactId>gwizard-healthchecks</artifactId>
 			<version>${gwizard.version}</version>
 		</dependency>
+		<dependency>
+		    <groupId>org.gwizard</groupId>
+		    <artifactId>gwizard-swagger</artifactId>
+		    <version>${gwizard.version}</version>
+		</dependency>
         <dependency>
             <groupId>io.dropwizard</groupId>
             <artifactId>dropwizard-jackson</artifactId>

src/main/java/com/example/app/ExampleConfig.java

@@ -4,6 +4,7 @@
 import org.gwizard.healthchecks.HealthChecksConfig;
 import org.gwizard.hibernate.DatabaseConfig;
 import org.gwizard.logging.LoggingConfig;
+import org.gwizard.swagger.SwaggerConfig;
 import org.gwizard.web.WebConfig;
 
 /**
@@ -23,4 +24,6 @@ public class ExampleConfig {
 	private WebConfig web = new WebConfig();
 	private DatabaseConfig database = new DatabaseConfig();
 	private HealthChecksConfig healthChecks = new HealthChecksConfig();
+	private SwaggerConfig swagger = new SwaggerConfig();
+
 }

src/main/java/com/example/app/ExampleModule.java

@@ -1,17 +1,21 @@
 package com.example.app;
 
+import javax.inject.Singleton;
+
+import org.gwizard.hibernate.DatabaseConfig;
+import org.gwizard.logging.LoggingConfig;
+import org.gwizard.swagger.SwaggerConfig;
+import org.gwizard.web.WebConfig;
+
 import com.example.app.resource.FunResource;
 import com.example.app.resource.ThingsResource;
 import com.example.app.services.ExampleService;
 import com.fasterxml.jackson.databind.DeserializationFeature;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import com.google.inject.AbstractModule;
 import com.google.inject.Provides;
+
 import io.dropwizard.jackson.Jackson;
-import org.gwizard.hibernate.DatabaseConfig;
-import org.gwizard.logging.LoggingConfig;
-import org.gwizard.web.WebConfig;
-import javax.inject.Singleton;
 
 /**
  * <p>Among the duties of your application module(s), you must explicitly bind every JAXRS resource class.
@@ -50,4 +54,10 @@ public WebConfig webConfig(ExampleConfig cfg) {
 	public DatabaseConfig databaseConfig(ExampleConfig cfg) {
 		return cfg.getDatabase();
 	}
+
+	@Provides
+	public SwaggerConfig swaggerConfig(ExampleConfig cfg) {
+		return cfg.getSwagger();
+	}
+
 }

src/main/java/com/example/app/Main.java

@@ -1,15 +1,18 @@
 package com.example.app;
 
-import com.google.inject.Guice;
-import com.google.inject.Injector;
+import java.io.File;
+
 import org.gwizard.config.ConfigModule;
 import org.gwizard.healthchecks.HealthChecksModule;
 import org.gwizard.hibernate.HibernateModule;
 import org.gwizard.logging.LoggingModule;
 import org.gwizard.metrics.MetricsModule;
 import org.gwizard.rest.RestModule;
 import org.gwizard.services.Run;
-import java.io.File;
+import org.gwizard.swagger.SwaggerModule;
+
+import com.google.inject.Guice;
+import com.google.inject.Injector;
 
 /**
  * Set up the injector and start all services
@@ -29,7 +32,8 @@ public static void main(String[] args) throws Exception {
 				new RestModule(),
 				new HibernateModule(),
 				new MetricsModule(),
-				new HealthChecksModule());
+				new HealthChecksModule(),
+				new SwaggerModule());
 
 		injector.getInstance(Run.class).start();
 	}

src/main/java/com/example/app/resource/ExampleApiConfig.java

@@ -0,0 +1,34 @@
+package com.example.app.resource;
+
+import io.swagger.annotations.Contact;
+import io.swagger.annotations.ExternalDocs;
+import io.swagger.annotations.Info;
+import io.swagger.annotations.License;
+import io.swagger.annotations.SwaggerDefinition;
+import io.swagger.annotations.Tag;
+
+@SwaggerDefinition(
+    info = @Info(
+      description = "Example Gwizard App",
+      version = "V1.0.1",
+      title = "The GWizard Example API",
+      termsOfService = "<http://localhost:8081/terms.html>",
+      contact = @Contact(
+            name = "Gandalf", 
+            email = "[email protected]", 
+            url = "<http://middleearth.org>"
+      ),
+      license = @License(
+            name = "Apache 2.0", 
+            url = "<http://www.apache.org/licenses/LICENSE-2.0>"
+      )
+    ),
+    consumes = {"application/json", "application/xml"},
+    produces = {"application/json", "application/xml"},
+    schemes = {SwaggerDefinition.Scheme.HTTP, SwaggerDefinition.Scheme.HTTPS},
+    tags = {
+            @Tag(name = "Private", description = "Tag used to denote operations as private")
+    }, 
+    externalDocs = @ExternalDocs(value = "Rings", url = "<http://ringsapi.io/middleearth.html>")
+)
+public interface ExampleApiConfig { /* empty */ }

src/main/java/com/example/app/resource/FunResource.java

@@ -2,6 +2,10 @@
 
 import com.codahale.metrics.annotation.Timed;
 import com.example.app.ExampleConfig;
+
+import io.swagger.annotations.ApiOperation;
+import io.swagger.annotations.ApiResponse;
+import io.swagger.annotations.ApiResponses;
 import lombok.Data;
 import javax.inject.Inject;
 import javax.ws.rs.Consumes;
@@ -33,6 +37,10 @@ public static class Stuff {
 		private final String foo;
 	}
 
+	@ApiOperation(tags={"stuff", "configuration"}, value="Returns some of this application configuration e.g. foo")
+	@ApiResponses(value={
+			@ApiResponse(code=200, message="OK")
+	})
 	@GET
 	public Stuff stuff() {
 		return new Stuff(cfg.getFoo());

test.yml

@@ -9,6 +9,10 @@
 
 foo: bar
 
+swagger:
+  resourcePackages: 
+  - com.example.app.resource  
+
 web:
   port: 8081