feat(swagger): Generate swagger descriptor for the Management Rest API

Closes gravitee-io/issues#184
gravitee-io · Sep 6, 2016 · 7ece387 · 7ece387
1 parent 8fba2db
commit 7ece387
Show file tree

Hide file tree

Showing 36 changed files with 729 additions and 194 deletions.
diff --git a/...i-model/src/main/java/io/gravitee/management/model/permissions/ApplicationPermission.java b/...i-model/src/main/java/io/gravitee/management/model/permissions/ApplicationPermission.java
@@ -22,7 +22,7 @@
 public enum ApplicationPermission {
 
     READ,
-    MANAGE_API,
+    MANAGE_APPLICATION,
     DELETE,
     MANAGE_MEMBERS,
     MANAGE_API_KEYS,

diff --git a/...nt-api-model/src/main/java/io/gravitee/management/model/permissions/PermissionHelper.java b/...nt-api-model/src/main/java/io/gravitee/management/model/permissions/PermissionHelper.java
@@ -59,7 +59,7 @@ public class PermissionHelper {
         applicationPermissionsByRole.put(MembershipType.OWNER, new ArrayList<ApplicationPermission>() {
             {
                 add(ApplicationPermission.READ);
-                add(ApplicationPermission.MANAGE_API);
+                add(ApplicationPermission.MANAGE_APPLICATION);
                 add(ApplicationPermission.ANALYTICS);
                 add(ApplicationPermission.MANAGE_API_KEYS);
                 add(ApplicationPermission.MANAGE_MEMBERS);
@@ -83,7 +83,7 @@ public class PermissionHelper {
         applicationPermissionsByRole.put(MembershipType.PRIMARY_OWNER, new ArrayList<ApplicationPermission>() {
             {
                 add(ApplicationPermission.READ);
-                add(ApplicationPermission.MANAGE_API);
+                add(ApplicationPermission.MANAGE_APPLICATION);
                 add(ApplicationPermission.ANALYTICS);
                 add(ApplicationPermission.MANAGE_API_KEYS);
                 add(ApplicationPermission.MANAGE_MEMBERS);

diff --git a/gravitee-management-api-rest/pom.xml b/gravitee-management-api-rest/pom.xml
@@ -30,6 +30,156 @@
 	<packaging>jar</packaging>
 	<name>Gravitee IO - Management - Rest API</name>
 
+	<properties>
+		<swagger2markup.version>1.0.1</swagger2markup.version>
+		<swagger2markup.plugin.version>1.0.1</swagger2markup.plugin.version>
+		<swagger2markup.extension.version>1.0.0</swagger2markup.extension.version>
+
+		<asciidoctorj.version>1.5.4</asciidoctorj.version>
+		<jruby.version>1.7.21</jruby.version>
+
+		<swagger.input>${project.basedir}/src/docs/swagger/swagger_petstore.yaml</swagger.input>
+		<asciidoctor.input.directory>${project.basedir}/src/adoc</asciidoctor.input.directory>
+		<generated.asciidoc.directory>${project.build.directory}/asciidoc</generated.asciidoc.directory>
+		<asciidoctor.html.output.directory>${project.build.directory}/asciidoc/html</asciidoctor.html.output.directory>
+		<asciidoctor.pdf.output.directory>${project.build.directory}/asciidoc/pdf</asciidoctor.pdf.output.directory>
+	</properties>
+
+	<build>
+		<plugins>
+			<plugin>
+				<groupId>com.github.kongchen</groupId>
+				<artifactId>swagger-maven-plugin</artifactId>
+				<version>3.1.3</version>
+				<configuration>
+					<apiSources>
+						<apiSource>
+							<springmvc>false</springmvc>
+							<locations>io.gravitee.management.rest.resource</locations>
+							<schemes>http,https</schemes>
+							<host>localhost:8083</host>
+							<basePath>/management</basePath>
+							<info>
+								<title>Gravitee.io - Rest API</title>
+								<version>${project.version}</version>
+								<description>This is description of the Gravitee Rest API</description>
+								<contact>
+									<email>contact@graviteesource.com</email>
+									<name>GraviteeSource</name>
+									<url>https://graviteesource.com</url>
+								</contact>
+								<license>
+									<url>http://www.apache.org/licenses/LICENSE-2.0.html</url>
+									<name>Apache 2.0</name>
+								</license>
+							</info>
+							<swaggerDirectory>${project.build.directory}/generated/descriptor/</swaggerDirectory>
+						</apiSource>
+					</apiSources>
+				</configuration>
+				<executions>
+					<execution>
+						<phase>compile</phase>
+						<goals>
+							<goal>generate</goal>
+						</goals>
+					</execution>
+				</executions>
+			</plugin>
+			<plugin>
+				<groupId>io.github.swagger2markup</groupId>
+				<artifactId>swagger2markup-maven-plugin</artifactId>
+				<version>${swagger2markup.plugin.version}</version>
+				<dependencies>
+					<dependency>
+						<groupId>io.github.swagger2markup</groupId>
+						<artifactId>swagger2markup-import-files-ext</artifactId>
+						<version>${swagger2markup.extension.version}</version>
+					</dependency>
+					<dependency>
+						<groupId>io.github.swagger2markup</groupId>
+						<artifactId>swagger2markup</artifactId>
+						<version>${swagger2markup.version}</version>
+					</dependency>
+				</dependencies>
+				<configuration>
+					<swaggerInput>${project.build.directory}/generated/descriptor/swagger.json</swaggerInput>
+					<outputDir>${generated.asciidoc.directory}</outputDir>
+					<config>
+						<swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
+						<swagger2markup.pathsGroupedBy>TAGS</swagger2markup.pathsGroupedBy>
+						<swagger2markup.extensions.dynamicOverview.contentPath>${project.basedir}/src/docs/asciidoc/extensions/overview</swagger2markup.extensions.dynamicOverview.contentPath>
+						<swagger2markup.extensions.dynamicDefinitions.contentPath>${project.basedir}/src/docs/asciidoc/extensions/definitions</swagger2markup.extensions.dynamicDefinitions.contentPath>
+						<swagger2markup.extensions.dynamicPaths.contentPath>${project.basedir}/src/docs/asciidoc/extensions/paths</swagger2markup.extensions.dynamicPaths.contentPath>
+						<swagger2markup.extensions.dynamicSecurity.contentPath>${project.basedir}src/docs/asciidoc/extensions/security</swagger2markup.extensions.dynamicSecurity.contentPath>
+					</config>
+				</configuration>
+				<executions>
+					<execution>
+						<phase>prepare-package</phase>
+						<goals>
+							<goal>convertSwagger2markup</goal>
+						</goals>
+					</execution>
+				</executions>
+			</plugin>
+
+			<!-- Run the generated asciidoc through Asciidoctor to generate
+                 other documentation types, such as PDFs or HTML5 -->
+			<plugin>
+				<groupId>org.asciidoctor</groupId>
+				<artifactId>asciidoctor-maven-plugin</artifactId>
+				<version>1.5.3</version>
+				<!-- Include Asciidoctor PDF for pdf generation -->
+				<dependencies>
+					<!-- Comment this section to use the default jruby artifact provided by the plugin -->
+					<dependency>
+						<groupId>org.jruby</groupId>
+						<artifactId>jruby-complete</artifactId>
+						<version>${jruby.version}</version>
+					</dependency>
+					<!-- Comment this section to use the default AsciidoctorJ artifact provided by the plugin -->
+					<dependency>
+						<groupId>org.asciidoctor</groupId>
+						<artifactId>asciidoctorj</artifactId>
+						<version>${asciidoctorj.version}</version>
+					</dependency>
+
+				</dependencies>
+				<!-- Configure generic document generation settings -->
+				<configuration>
+					<sourceDirectory>${asciidoctor.input.directory}</sourceDirectory>
+					<sourceDocumentName>index.adoc</sourceDocumentName>
+					<attributes>
+						<doctype>book</doctype>
+						<toc>left</toc>
+						<toclevels>3</toclevels>
+						<numbered></numbered>
+						<hardbreaks></hardbreaks>
+						<sectlinks></sectlinks>
+						<sectanchors></sectanchors>
+						<generated>${generated.asciidoc.directory}</generated>
+					</attributes>
+				</configuration>
+				<!-- Since each execution can only handle one backend, run
+                     separate executions for each desired output type -->
+				<executions>
+					<execution>
+						<id>output-html</id>
+						<phase>package</phase>
+						<goals>
+							<goal>process-asciidoc</goal>
+						</goals>
+						<configuration>
+							<backend>html5</backend>
+							<outputDirectory>${asciidoctor.html.output.directory}</outputDirectory>
+						</configuration>
+					</execution>
+				</executions>
+			</plugin>
+		</plugins>
+	</build>
+
 	<dependencies>
 		<!-- Gravitee Management dependencies-->
 		<dependency>
@@ -103,6 +253,13 @@
 			</exclusions>
 		</dependency>
 
+		<!-- Swagger -->
+		<dependency>
+			<groupId>io.swagger</groupId>
+			<artifactId>swagger-jersey2-jaxrs</artifactId>
+			<version>1.5.8</version>
+		</dependency>
+
 		<dependency>
 			<groupId>commons-lang</groupId>
 			<artifactId>commons-lang</artifactId>
@@ -145,4 +302,20 @@
 			<artifactId>assertj-core</artifactId>
 		</dependency>
 	</dependencies>
+
+	<pluginRepositories>
+		<pluginRepository>
+			<id>jcenter-snapshots</id>
+			<name>jcenter</name>
+			<url>http://oss.jfrog.org/artifactory/oss-snapshot-local/</url>
+		</pluginRepository>
+		<pluginRepository>
+			<snapshots>
+				<enabled>false</enabled>
+			</snapshots>
+			<id>jcenter-releases</id>
+			<name>jcenter</name>
+			<url>http://jcenter.bintray.com</url>
+		</pluginRepository>
+	</pluginRepositories>
 </project>
diff --git a/gravitee-management-api-rest/src/adoc/index.adoc b/gravitee-management-api-rest/src/adoc/index.adoc
@@ -0,0 +1,4 @@
+include::{generated}/overview.adoc[]
+include::{generated}/security.adoc[]
+include::{generated}/paths.adoc[]
+include::{generated}/definitions.adoc[]
diff --git a/...ent-api-rest/src/main/java/io/gravitee/management/rest/resource/ApiAnalyticsResource.java b/...ent-api-rest/src/main/java/io/gravitee/management/rest/resource/ApiAnalyticsResource.java
@@ -21,6 +21,8 @@
 import io.gravitee.management.rest.resource.param.AnalyticsParam;
 import io.gravitee.management.rest.security.ApiPermissionsRequired;
 import io.gravitee.management.service.AnalyticsService;
+import io.swagger.annotations.Api;
+import io.swagger.annotations.ApiOperation;
 
 import javax.inject.Inject;
 import javax.ws.rs.BeanParam;
@@ -33,17 +35,18 @@
  * @author David BRASSELY (brasseld at gmail.com)
  */
 @ApiPermissionsRequired(ApiPermission.ANALYTICS)
+@Api(tags = {"API"})
 public class ApiAnalyticsResource extends AbstractResource {
 
-    @PathParam("api")
-    private String api;
-
     @Inject
     private AnalyticsService analyticsService;
 
     @GET
     @Produces(MediaType.APPLICATION_JSON)
-    public Response hits(@BeanParam AnalyticsParam analyticsParam) {
+    @ApiOperation(value = "Get API analytics")
+    public Response hits(
+            @PathParam("api") String api,
+            @BeanParam AnalyticsParam analyticsParam) {
         analyticsParam.validate();
 
         Analytics analytics = null;

diff --git a/...gement-api-rest/src/main/java/io/gravitee/management/rest/resource/ApiEventsResource.java b/...gement-api-rest/src/main/java/io/gravitee/management/rest/resource/ApiEventsResource.java
@@ -15,36 +15,40 @@
  */
 package io.gravitee.management.rest.resource;
 
-import java.util.List;
-import java.util.stream.Collectors;
-
-import javax.inject.Inject;
-import javax.ws.rs.*;
-
 import io.gravitee.common.http.MediaType;
-
 import io.gravitee.management.model.EventEntity;
 import io.gravitee.management.model.permissions.ApiPermission;
 import io.gravitee.management.rest.resource.param.EventTypeListParam;
 import io.gravitee.management.rest.security.ApiPermissionsRequired;
 import io.gravitee.management.service.EventService;
+import io.swagger.annotations.*;
+
+import javax.inject.Inject;
+import javax.ws.rs.*;
+import java.util.List;
+import java.util.stream.Collectors;
 
 /**
  * @author Titouan COMPIEGNE (titouan.compiegne at gravitee.io)
  * @author GraviteeSource Team
  */
 @ApiPermissionsRequired(ApiPermission.MANAGE_LIFECYCLE)
+@Api(tags = {"API"})
 public class ApiEventsResource extends AbstractResource {
 
-    @PathParam("api")
-    private String api;
-
     @Inject
     private EventService eventService;
 
     @GET
     @Produces(MediaType.APPLICATION_JSON)
-    public List<EventEntity> events(@DefaultValue("all") @QueryParam("type") EventTypeListParam eventTypeListParam) {
+    @ApiOperation(value = "Get API's events",
+            notes = "User must have the MANAGE_LIFECYCLE permission to use this service")
+    @ApiResponses({
+            @ApiResponse(code = 200, message = "API's events"),
+            @ApiResponse(code = 500, message = "Internal server error")})
+    public List<EventEntity> events(
+            @PathParam("api") String api,
+            @ApiParam @DefaultValue("all") @QueryParam("type") EventTypeListParam eventTypeListParam) {
         return eventService.findByApi(api).stream()
                 .filter(event -> eventTypeListParam.getEventTypes().contains(event.getType()))
                 .sorted((e1, e2) -> e2.getCreatedAt().compareTo(e1.getCreatedAt()))

diff --git a/...gement-api-rest/src/main/java/io/gravitee/management/rest/resource/ApiHealthResource.java b/...gement-api-rest/src/main/java/io/gravitee/management/rest/resource/ApiHealthResource.java
@@ -20,6 +20,8 @@
 import io.gravitee.management.rest.resource.param.HealthParam;
 import io.gravitee.management.rest.security.ApiPermissionsRequired;
 import io.gravitee.management.service.AnalyticsService;
+import io.swagger.annotations.Api;
+import io.swagger.annotations.ApiOperation;
 
 import javax.inject.Inject;
 import javax.ws.rs.BeanParam;
@@ -32,17 +34,20 @@
  * @author David BRASSELY (brasseld at gmail.com)
  */
 @ApiPermissionsRequired(ApiPermission.ANALYTICS)
+@Api(tags = {"API"})
 public class ApiHealthResource extends AbstractResource {
 
-    @PathParam("api")
-    private String api;
-
     @Inject
     private AnalyticsService analyticsService;
 
     @GET
     @Produces(MediaType.APPLICATION_JSON)
-    public Response hits(@BeanParam HealthParam healthParam) {
+    @ApiOperation(
+            value = "Health statistics for API"
+    )
+    public Response health(
+            @PathParam("api") String api,
+            @BeanParam HealthParam healthParam) {
         healthParam.validate();
 
         return Response.ok(analyticsService.health(

diff --git a/...-api-rest/src/main/java/io/gravitee/management/rest/resource/ApiKeyAnalyticsResource.java b/...-api-rest/src/main/java/io/gravitee/management/rest/resource/ApiKeyAnalyticsResource.java
@@ -25,6 +25,7 @@
 import io.gravitee.management.service.ApiKeyService;
 import io.gravitee.management.service.exceptions.ApiNotFoundException;
 import io.gravitee.management.service.exceptions.NoValidApiKeyException;
+import io.swagger.annotations.Api;
 
 import javax.inject.Inject;
 import javax.ws.rs.BeanParam;
@@ -38,6 +39,7 @@
  * @author David BRASSELY (brasseld at gmail.com)
  */
 @ApplicationPermissionsRequired(ApplicationPermission.MANAGE_API_KEYS)
+@Api(tags = {"Application"})
 public class ApiKeyAnalyticsResource extends AbstractResource {
 
     @PathParam("application")
@@ -54,7 +56,7 @@ public class ApiKeyAnalyticsResource extends AbstractResource {
 
     @GET
     @Produces(MediaType.APPLICATION_JSON)
-    public Response hits(@BeanParam AnalyticsParam analyticsParam) throws ApiNotFoundException {
+    public Response applicationAnalytics(@BeanParam AnalyticsParam analyticsParam) throws ApiNotFoundException {
         Optional<ApiKeyEntity> apiKeyEntity = apiKeyService.getCurrent(application, null);
 
         if (! apiKeyEntity.isPresent()) {