Merge pull request #3736 from guusdk/api-documentation

Improving the generated REST API documentation

services/pom.xml

@@ -31,7 +31,7 @@
     <description />
 
     <properties>
-        <version.swagger.doclet>1.0.5</version.swagger.doclet>
+        <version.swagger.doclet>1.1.2</version.swagger.doclet>
         <maven.compiler.target>1.8</maven.compiler.target>
         <maven.compiler.source>1.8</maven.compiler.source>
     </properties>
@@ -205,6 +205,16 @@
                     <url>http://jcenter.bintray.com</url>
                 </repository>
             </repositories>
+            <pluginRepositories>
+                <pluginRepository>
+                    <snapshots>
+                        <enabled>false</enabled>
+                    </snapshots>
+                    <id>central</id>
+                    <name>bintray</name>
+                    <url>http://jcenter.bintray.com</url>
+                </pluginRepository>
+            </pluginRepositories>
 
             <build>
                 <plugins>
@@ -244,29 +254,24 @@
                     </plugin>
 
                     <plugin>
-                        <groupId>com.redowlanalytics</groupId>
+                        <groupId>io.github.swagger2markup</groupId>
                         <artifactId>swagger2markup-maven-plugin</artifactId>
-                        <version>0.7.1</version>
+                        <version>1.1.0</version>
-
-                        <dependencies>
-                            <dependency>
-                                <groupId>io.github.robwin</groupId>
-                                <artifactId>swagger2markup</artifactId>
-                                <version>0.7.1</version>
-                            </dependency>
-                        </dependencies>
 
                         <executions>
                             <execution>
                                 <id>gen-asciidoc</id>
                                 <phase>process-resources</phase>
                                 <goals>
-                                    <goal>process-swagger</goal>
+                                    <goal>convertSwagger2markup</goal>
                                 </goals>
                                 <configuration>
-                                    <inputDirectory>${project.basedir}/target/apidocs-rest/swagger/apidocs</inputDirectory>
+                                    <swaggerInput>${project.build.directory}/apidocs-rest/swagger/apidocs/service.json</swaggerInput>
-                                    <outputDirectory>${project.basedir}/target/apidocs-rest/asciidoc</outputDirectory>
+                                    <outputDir>${project.build.directory}/apidocs-rest/asciidoc/</outputDir>
-                                    <markupLanguage>asciidoc</markupLanguage>
+                                    <config>
+                                        <swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
+                                        <swagger2markup.pathsGroupedBy>TAGS</swagger2markup.pathsGroupedBy>
+                                    </config>
                                 </configuration>
                             </execution>
                         </executions>
@@ -275,7 +280,7 @@
                     <plugin>
                         <groupId>org.asciidoctor</groupId>
                         <artifactId>asciidoctor-maven-plugin</artifactId>
-                        <version>1.5.2</version>
+                        <version>1.5.3</version>
                         <executions>
                             <execution>
                                 <id>generate-docs</id>
@@ -293,6 +298,7 @@
                                         https://github.com/asciidoctor/asciidoctorj/blob/master/asciidoctorj-core/src/main/java/org/asciidoctor/Attributes.java
                                          -->
                                         <toc/>
+                                        <toc-position>left</toc-position>
                                         <generated>${project.basedir}/target/apidocs-rest/asciidoc</generated>
                                     </attributes>
                                 </configuration>

services/src/main/java/org/keycloak/services/resources/admin/AttackDetectionResource.java

@@ -42,6 +42,7 @@ import java.util.Map;
 /**
  * Base resource class for the admin REST api of one realm
  *
+ * @resource Attack Detection
  * @author <a href="mailto:bill@burkecentral.com">Bill Burke</a>
  * @version $Revision: 1 $
  */

services/src/main/java/org/keycloak/services/resources/admin/AuthenticationManagementResource.java

@@ -73,6 +73,7 @@ import java.util.Map;
 import static javax.ws.rs.core.Response.Status.NOT_FOUND;
 
 /**
+ * @resource Authentication Management
  * @author Bill Burke
  */
 public class AuthenticationManagementResource {

services/src/main/java/org/keycloak/services/resources/admin/ClientAttributeCertificateResource.java

@@ -62,6 +62,7 @@ import java.util.List;
 import java.util.Map;
 
 /**
+ * @resource Client Attribute Certificate
  * @author <a href="mailto:bill@burkecentral.com">Bill Burke</a>
  * @version $Revision: 1 $
  */

services/src/main/java/org/keycloak/services/resources/admin/ClientInitialAccessResource.java

@@ -43,6 +43,7 @@ import java.util.LinkedList;
 import java.util.List;
 
 /**
+ * @resource Client Initial Access
  * @author <a href="mailto:sthorger@redhat.com">Stian Thorgersen</a>
  */
 public class ClientInitialAccessResource {

services/src/main/java/org/keycloak/services/resources/admin/ClientRegistrationPolicyResource.java

@@ -39,6 +39,7 @@ import org.keycloak.services.clientregistration.policy.ClientRegistrationPolicy;
 import org.keycloak.services.clientregistration.policy.ClientRegistrationPolicyFactory;
 
 /**
+ * @resource Client Registration Policy
  * @author <a href="mailto:mposolda@redhat.com">Marek Posolda</a>
  */
 public class ClientRegistrationPolicyResource {

services/src/main/java/org/keycloak/services/resources/admin/ClientResource.java

@@ -82,6 +82,7 @@ import static java.lang.Boolean.TRUE;
 /**
  * Base resource class for managing one particular client of a realm.
  *
+ * @resource Clients
  * @author <a href="mailto:bill@burkecentral.com">Bill Burke</a>
  * @version $Revision: 1 $
  */

services/src/main/java/org/keycloak/services/resources/admin/ClientRoleMappingsResource.java

@@ -49,6 +49,7 @@ import java.util.Properties;
 import java.util.Set;
 
 /**
+ * @resource Client Role Mappings
  * @author <a href="mailto:bill@burkecentral.com">Bill Burke</a>
  * @version $Revision: 1 $
  */

services/src/main/java/org/keycloak/services/resources/admin/ClientTemplateResource.java

@@ -47,6 +47,7 @@ import javax.ws.rs.core.UriInfo;
 /**
  * Base resource class for managing one particular client of a realm.
  *
+ * @resource Client Templates
  * @author <a href="mailto:bill@burkecentral.com">Bill Burke</a>
  * @version $Revision: 1 $
  */

services/src/main/java/org/keycloak/services/resources/admin/ClientTemplatesResource.java

@@ -46,6 +46,7 @@ import java.util.List;
 /**
  * Base resource class for managing a realm's client templates.
  *
+ * @resource Client Templates
  * @author <a href="mailto:bill@burkecentral.com">Bill Burke</a>
  * @version $Revision: 1 $
  */

services/src/main/java/org/keycloak/services/resources/admin/ClientsResource.java

@@ -58,6 +58,7 @@ import java.util.Properties;
 /**
  * Base resource class for managing a realm's clients.
  *
+ * @resource Clients
  * @author <a href="mailto:bill@burkecentral.com">Bill Burke</a>
  * @version $Revision: 1 $
  */

services/src/main/java/org/keycloak/services/resources/admin/ComponentResource.java

@@ -65,6 +65,7 @@ import java.util.Properties;
 import java.util.stream.Collectors;
 
 /**
+ * @resource Component
  * @author <a href="mailto:bill@burkecentral.com">Bill Burke</a>
  * @version $Revision: 1 $
  */

services/src/main/java/org/keycloak/services/resources/admin/GroupResource.java

@@ -51,6 +51,7 @@ import java.util.Set;
 import org.keycloak.services.ErrorResponse;
 
 /**
+ * @resource Groups
  * @author Bill Burke
  */
 public class GroupResource {

services/src/main/java/org/keycloak/services/resources/admin/GroupsResource.java

@@ -42,6 +42,7 @@ import java.util.List;
 import org.keycloak.services.ErrorResponse;
 
 /**
+ * @resource Groups
  * @author Bill Burke
  */
 public class GroupsResource {

services/src/main/java/org/keycloak/services/resources/admin/IdentityProviderResource.java

@@ -65,6 +65,7 @@ import java.util.List;
 import java.util.Map;
 
 /**
+ * @resource Identity Providers
  * @author Pedro Igor
  */
 public class IdentityProviderResource {

services/src/main/java/org/keycloak/services/resources/admin/IdentityProvidersResource.java

@@ -58,6 +58,7 @@ import java.util.Map;
 import static javax.ws.rs.core.Response.Status.BAD_REQUEST;
 
 /**
+ * @resource Identity Providers
  * @author Pedro Igor
  */
 public class IdentityProvidersResource {

services/src/main/java/org/keycloak/services/resources/admin/KeyResource.java

@@ -36,6 +36,7 @@ import java.util.List;
 import java.util.Map;
 
 /**
+ * @resource Key
  * @author <a href="mailto:sthorger@redhat.com">Stian Thorgersen</a>
  */
 public class KeyResource {

services/src/main/java/org/keycloak/services/resources/admin/ProtocolMappersResource.java

@@ -55,6 +55,7 @@ import java.util.Properties;
 /**
  * Base resource for managing users
  *
+ * @resource Protocol Mappers
  * @author <a href="mailto:bill@burkecentral.com">Bill Burke</a>
  * @version $Revision: 1 $
  */

services/src/main/java/org/keycloak/services/resources/admin/RealmAdminResource.java

@@ -102,6 +102,7 @@ import java.util.regex.PatternSyntaxException;
 /**
  * Base resource class for the admin REST api of one realm
  *
+ * @resource Realms Admin
  * @author <a href="mailto:bill@burkecentral.com">Bill Burke</a>
  * @version $Revision: 1 $
  */

services/src/main/java/org/keycloak/services/resources/admin/RealmsAdminResource.java

@@ -54,6 +54,7 @@ import java.util.List;
 /**
  * Top level resource for Admin REST API
  *
+ * @resource Realms Admin
  * @author <a href="mailto:bill@burkecentral.com">Bill Burke</a>
  * @version $Revision: 1 $
  */

services/src/main/java/org/keycloak/services/resources/admin/RoleByIdResource.java

@@ -45,6 +45,7 @@ import java.util.Set;
 /**
  * Sometimes its easier to just interact with roles by their ID instead of container/role-name
  *
+ * @resource Roles (by ID)
  * @author <a href="mailto:bill@burkecentral.com">Bill Burke</a>
  * @version $Revision: 1 $
  */

services/src/main/java/org/keycloak/services/resources/admin/RoleContainerResource.java

@@ -48,6 +48,7 @@ import java.util.List;
 import java.util.Set;
 
 /**
+ * @resource Roles
  * @author <a href="mailto:bill@burkecentral.com">Bill Burke</a>
  * @version $Revision: 1 $
  */

services/src/main/java/org/keycloak/services/resources/admin/RoleMapperResource.java

@@ -59,6 +59,7 @@ import java.util.Set;
 /**
  * Base resource for managing users
  *
+ * @resource Role Mapper
  * @author <a href="mailto:bill@burkecentral.com">Bill Burke</a>
  * @version $Revision: 1 $
  */

services/src/main/java/org/keycloak/services/resources/admin/RoleResource.java

@@ -33,6 +33,7 @@ import java.util.List;
 import java.util.Set;
 
 /**
+ * @resource Roles
  * @author <a href="mailto:bill@burkecentral.com">Bill Burke</a>
  * @version $Revision: 1 $
  */

services/src/main/java/org/keycloak/services/resources/admin/ScopeMappedClientResource.java

@@ -43,6 +43,7 @@ import java.util.List;
 import java.util.Set;
 
 /**
+ * @resource Scope Mappings
  * @author <a href="mailto:bill@burkecentral.com">Bill Burke</a>
  * @version $Revision: 1 $
  */

services/src/main/java/org/keycloak/services/resources/admin/ScopeMappedResource.java

@@ -50,6 +50,7 @@ import java.util.Set;
 /**
  * Base class for managing the scope mappings of a specific client.
  *
+ * @resource Scope Mappings
  * @author <a href="mailto:bill@burkecentral.com">Bill Burke</a>
  * @version $Revision: 1 $
  */

services/src/main/java/org/keycloak/services/resources/admin/UserStorageProviderResource.java

@@ -46,6 +46,7 @@ import java.util.HashMap;
 import java.util.Map;
 
 /**
+ * @resource User Storage Provider
  * @author <a href="mailto:bill@burkecentral.com">Bill Burke</a>
  * @version $Revision: 1 $
  */

services/src/main/java/org/keycloak/services/resources/admin/UsersResource.java

@@ -107,6 +107,7 @@ import java.util.concurrent.TimeUnit;
 /**
  * Base resource for managing users
  *
+ * @resource Users
  * @author <a href="mailto:bill@burkecentral.com">Bill Burke</a>
  * @version $Revision: 1 $
  */