diff --git a/distribution/docs-dist/assembly.xml b/distribution/docs-dist/assembly.xml
index 879e92c6d1..c1a1bd97dd 100755
--- a/distribution/docs-dist/assembly.xml
+++ b/distribution/docs-dist/assembly.xml
@@ -13,7 +13,7 @@
             <outputDirectory>javadocs</outputDirectory>
         </fileSet>
         <fileSet>
-            <directory>../../services/target/apidocs</directory>
+            <directory>../../services/target/apidocs-rest/output</directory>
             <outputDirectory>rest-api</outputDirectory>
         </fileSet>
         <fileSet>
diff --git a/services/pom.xml b/services/pom.xml
index 41d80e752f..25e1756547 100755
--- a/services/pom.xml
+++ b/services/pom.xml
@@ -13,6 +13,10 @@
     <name>Keycloak REST Services</name>
     <description />
 
+    <properties>
+        <version.swagger.doclet>1.0.5</version.swagger.doclet>
+    </properties>
+
     <dependencies>
         <dependency>
             <groupId>org.bouncycastle</groupId>
@@ -188,27 +192,114 @@
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-javadoc-plugin</artifactId>
-                <configuration>
-                    <subpackages>org.keycloak.services.resources.admin:org.keycloak.protocol.oidc</subpackages>
-                    <doclet>com.lunatech.doclets.jax.jaxrs.JAXRSDoclet</doclet>
-                    <docletArtifacts>
-                        <docletArtifact>
-                            <groupId>com.lunatech.jax-doclets</groupId>
-                            <artifactId>doclets</artifactId>
-                            <version>0.10.2</version>
-                        </docletArtifact>
-                    </docletArtifacts>
-                    <detectOfflineLinks>false</detectOfflineLinks>
-                    <offlineLinks>
-                        <offlineLink>
-                            <url>../javadocs</url>
-                            <location>${project.basedir}/../target/site/apidocs</location>
-                        </offlineLink>
-                    </offlineLinks>
-                    <additionalparam>-disablejavascriptexample</additionalparam>
-                    <additionalparam>-pathexcludefilter '/admin/.*index.*' -pathexcludefilter '/admin' -pathexcludefilter '/admin/\\{realm\\}/console.*'</additionalparam>
-                </configuration>
+                <executions>
+                    <execution>
+                        <id>generate-service-docs</id>
+                        <phase>generate-resources</phase>
+                        <configuration>
+                            <doclet>com.carma.swagger.doclet.ServiceDoclet</doclet>
+                            <docletArtifact>
+                                <groupId>com.carma</groupId>
+                                <artifactId>swagger-doclet</artifactId>
+                                <version>${version.swagger.doclet}</version>
+                            </docletArtifact>
+
+                            <subpackages>org.keycloak.services.resources.admin:org.keycloak.protocol.oidc</subpackages>
+                            <detectOfflineLinks>false</detectOfflineLinks>
+                            <offlineLinks>
+                                <offlineLink>
+                                    <url>../javadocs</url>
+                                    <location>${project.basedir}/../target/site/apidocs</location>
+                                </offlineLink>
+                            </offlineLinks>
+
+                            <reportOutputDirectory>${project.basedir}/target/apidocs-rest/swagger</reportOutputDirectory>
+                            <useStandardDocletOptions>false</useStandardDocletOptions>
+                            <additionalparam> -skipUiFiles -apiVersion 1 -includeResourcePrefixes org.keycloak.services.resources.admin,org.keycloak.protocol.oidc -docBasePath /apidocs -apiBasePath http://localhost:8080/auth -apiInfoFile ${project.basedir}/src/docs/swagger/apiinfo.json</additionalparam>
+                        </configuration>
+                        <goals>
+                            <goal>javadoc</goal>
+                        </goals>
+                    </execution>
+                </executions>
             </plugin>
         </plugins>
     </build>
+
+    <profiles>
+        <profile>
+            <id>jboss-release</id>
+
+            <repositories>
+                <repository>
+                    <snapshots>
+                        <enabled>false</enabled>
+                    </snapshots>
+                    <id>central</id>
+                    <name>bintray</name>
+                    <url>http://jcenter.bintray.com</url>
+                </repository>
+            </repositories>
+
+            <build>
+                <plugins>
+                    <plugin>
+                        <groupId>com.redowlanalytics</groupId>
+                        <artifactId>swagger2markup-maven-plugin</artifactId>
+                        <version>0.7.1</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>
+                                </goals>
+                                <configuration>
+                                    <inputDirectory>${project.basedir}/target/apidocs-rest/swagger/apidocs</inputDirectory>
+                                    <outputDirectory>${project.basedir}/target/apidocs-rest/asciidoc</outputDirectory>
+                                    <markupLanguage>asciidoc</markupLanguage>
+                                </configuration>
+                            </execution>
+                        </executions>
+                    </plugin>
+
+                    <plugin>
+                        <groupId>org.asciidoctor</groupId>
+                        <artifactId>asciidoctor-maven-plugin</artifactId>
+                        <version>1.5.2</version>
+                        <executions>
+                            <execution>
+                                <id>generate-docs</id>
+                                <phase>package</phase>
+                                <goals>
+                                    <goal>process-asciidoc</goal>
+                                </goals>
+                                <configuration>
+                                    <sourceDirectory>${project.basedir}/src/docs/asciidoc</sourceDirectory>
+                                    <sourceDocumentName>index.adoc</sourceDocumentName>
+                                    <outputDirectory>${project.basedir}/target/apidocs-rest/output</outputDirectory>
+                                    <backend>html5</backend>
+                                    <attributes>
+                                        <!-- List of attributes:
+                                        https://github.com/asciidoctor/asciidoctorj/blob/master/asciidoctorj-core/src/main/java/org/asciidoctor/Attributes.java
+                                         -->
+                                        <generated>${project.basedir}/target/apidocs-rest/asciidoc</generated>
+                                    </attributes>
+                                </configuration>
+                            </execution>
+                        </executions>
+                    </plugin>
+                </plugins>
+            </build>
+        </profile>
+    </profiles>
 </project>
diff --git a/services/src/docs/asciidoc/index.adoc b/services/src/docs/asciidoc/index.adoc
new file mode 100644
index 0000000000..226d206aca
--- /dev/null
+++ b/services/src/docs/asciidoc/index.adoc
@@ -0,0 +1,3 @@
+include::{generated}/overview.adoc[]
+include::{generated}/paths.adoc[]
+include::{generated}/definitions.adoc[]
\ No newline at end of file
diff --git a/services/src/docs/swagger/apiinfo.json b/services/src/docs/swagger/apiinfo.json
new file mode 100644
index 0000000000..575955f57d
--- /dev/null
+++ b/services/src/docs/swagger/apiinfo.json
@@ -0,0 +1,4 @@
+{
+  "title": "Keycloak Admin REST API",
+  "description": "This is a REST API reference for the Keycloak Admin"
+}
\ No newline at end of file
diff --git a/services/src/main/java/org/keycloak/services/resources/admin/AdminRoot.java b/services/src/main/java/org/keycloak/services/resources/admin/AdminRoot.java
index d57e96ee32..834d957324 100755
--- a/services/src/main/java/org/keycloak/services/resources/admin/AdminRoot.java
+++ b/services/src/main/java/org/keycloak/services/resources/admin/AdminRoot.java
@@ -77,6 +77,7 @@ public class AdminRoot {
     /**
      * Convenience path to master realm admin console
      *
+     * @exclude
      * @return
      */
     @GET
@@ -90,6 +91,7 @@ public class AdminRoot {
     /**
      * Convenience path to master realm admin console
      *
+     * @exclude
      * @return
      */
     @Path("index.{html:html}") // expression is actually "index.html" but this is a hack to get around jax-doclet bug
@@ -118,6 +120,7 @@ public class AdminRoot {
     /**
      * path to realm admin console ui
      *
+     * @exclude
      * @param name Realm name (not id!)
      * @return
      */