Merge pull request #3736 from guusdk/api-documentation
Improving the generated REST API documentation
This commit is contained in:
Stian Thorgersen
GitHub
commit
faf0e98665
28 changed files with 49 additions and 16 deletions
|
|
@ -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>
|
||||
|
||||
<dependencies>
|
||||
<dependency>
|
||||
<groupId>io.github.robwin</groupId>
|
||||
<artifactId>swagger2markup</artifactId>
|
||||
<version>0.7.1</version>
|
||||
</dependency>
|
||||
</dependencies>
|
||||
<version>1.1.0</version>
|
||||
|
||||
<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>
|
||||
<outputDirectory>${project.basedir}/target/apidocs-rest/asciidoc</outputDirectory>
|
||||
<markupLanguage>asciidoc</markupLanguage>
|
||||
<swaggerInput>${project.build.directory}/apidocs-rest/swagger/apidocs/service.json</swaggerInput>
|
||||
<outputDir>${project.build.directory}/apidocs-rest/asciidoc/</outputDir>
|
||||
<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>
|
||||
|
|
|
|||
|
|
@ -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 $
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -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 {
|
||||
|
|
|
|||
|
|
@ -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 $
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -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 {
|
||||
|
|
|
|||
|
|
@ -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 {
|
||||
|
|
|
|||
|
|
@ -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 $
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -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 $
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -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 $
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -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 $
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -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 $
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -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 $
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -51,6 +51,7 @@ import java.util.Set;
|
|||
import org.keycloak.services.ErrorResponse;
|
||||
|
||||
/**
|
||||
* @resource Groups
|
||||
* @author Bill Burke
|
||||
*/
|
||||
public class GroupResource {
|
||||
|
|
|
|||
|
|
@ -42,6 +42,7 @@ import java.util.List;
|
|||
import org.keycloak.services.ErrorResponse;
|
||||
|
||||
/**
|
||||
* @resource Groups
|
||||
* @author Bill Burke
|
||||
*/
|
||||
public class GroupsResource {
|
||||
|
|
|
|||
|
|
@ -65,6 +65,7 @@ import java.util.List;
|
|||
import java.util.Map;
|
||||
|
||||
/**
|
||||
* @resource Identity Providers
|
||||
* @author Pedro Igor
|
||||
*/
|
||||
public class IdentityProviderResource {
|
||||
|
|
|
|||
|
|
@ -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 {
|
||||
|
|
|
|||
|
|
@ -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 {
|
||||
|
|
|
|||
|
|
@ -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 $
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -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 $
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -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 $
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -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 $
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -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 $
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -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 $
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -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 $
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -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 $
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -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 $
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -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 $
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -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 $
|
||||
*/
|
||||
|
|
|
|||
Loading…
Reference in a new issue