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

[Stan Silvert]

+1 overall.  Comments below.

On 10/16/2014 6:54 AM, Stian Thorgersen wrote:
> 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
This part is a no-brainer.  I think we should do it right away.
> 2. Add ProviderDescription[1] interface, ProviderFactory implementations can optionally implement this interface. All our built-in providers should implement ProviderDescription
I'd like us to give this more thought before we commit.  One of the 
problems I ran into with tighter WildFly integration was that 
keycloak-server.json doesn't translate very well into DMR.   So I'd like 
to see that our config options and types will work with that.

DMR already has two-way JSON translation built in because JSON is used 
as its wire format.  Perhaps we should adopt that as our standard.  It's 
a tiny library and it's very nice to work with.  The public API is only 
three classes.

We would just need to make sure our JSON is readable with 
ModelNode.fromJSONStream().
> 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)
You'll also need lists, arrays, a "type" type, etc.  DMR already has 
this stuff and it's mature.  I think it would fit perfectly.  Just use 
DMR's ModelType.Type enum instead of your custom enum.

You might also want to think about things like localization of 
getDescription() and using a validation framework in case "isRequired" 
isn't enough.  WildFly has libraries for all that stuff too if we want 
to use it.
>
> --------------
> #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}"
>          }
>      }
> _______________________________________________
> keycloak-dev mailing list
> keycloak-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/keycloak-dev