[keycloak-dev] Documenting SPIs, providers and keycloak-server.json

[Stian Thorgersen]

To make it easier for users to configure Keycloak I propose we add a self-documenting feature to SPIs and Providers. 

This would also allow us to do some sanity check on keycloak-server.json.

To achieve this we would do the following:

1. Add Spi#getDescription and update all implementations to have a short description about the Spi
2. Add ProviderDescription[1] interface, ProviderFactory implementations can optionally implement this interface. All our built-in providers should implement ProviderDescription
3. Add some sanity check of keycloak-server.json
4. Fix config in keycloak-server.json that doesn't follow the spi/provider format (applies to scheduled and theme)

Using the above details we can generate a reference guide to include in the documentation. In the future we could also make it possible to configure through the admin console.

It's only a couple hours work and I'd like to include it in 1.1.0.Beta1.

More details below.

--------------
#2 Add ProviderDescription

ProviderDescription:
* String getDescription
* ConfigOption[] getConfigOptions()

ConfigOption:
* String getName
* String getDescription
* boolean isRequired
* Type getType

Type (enum)
* STRING
* NUMBER
* BOOLEAN
* OPTIONS(String.. options)

--------------
#4 Fix config in keycloak-server.json

Change:

    "scheduled": {
        "interval": 900
    }

To:

    "timer": {
        "basic": 
          "defaultInterval: 900
        }
    }

Change:

    "theme": {
        "default": "keycloak",
        "staticMaxAge": 2592000,
        "cacheTemplates": "${keycloak.theme.cacheTemplates:true}",
        "cacheThemes": "${keycloak.theme.cacheThemes:true}",
        "folder": {
            "dir": "${keycloak.theme.dir}"
        }
    }

To:

    "theme": {
        "provider": "default",
        "default": {
            "defaultTheme": "keycloak",
            "staticMaxAge": 2592000,
            "cacheTemplates": "${keycloak.theme.cacheTemplates:true}",
            "cacheThemes": "${keycloak.theme.cacheThemes:true}",
            "themeDir": "${keycloak.theme.dir}"
        }
    }