Add YAML examples for staticRules and interceptUrlMap

plugin-core/docs/src/docs/requestMappings/configGroovyMap.adoc

@@ -20,18 +20,29 @@ under the License.
 [[configGroovyMap]]
 === Static Map
 
-To use a static map in `application.groovy` to secure URLs, first specify `securityConfigType="InterceptUrlMap"`:
+To use a static map to secure URLs, first specify `securityConfigType="InterceptUrlMap"`:
 
 [source,groovy]
-.Listing {counter:listing}. Specifying `securityConfigType` as "`InterceptUrlMap`"
+.Listing {counter:listing}. Specifying `securityConfigType` as "`InterceptUrlMap`" in `application.groovy`
 ----
 grails.plugin.springsecurity.securityConfigType = "InterceptUrlMap"
 ----
 
-Define a Map in `application.groovy`:
+Or in `application.yml`:
+
+[source,yaml]
+.Listing {counter:listing}. Specifying `securityConfigType` as "`InterceptUrlMap`" in `application.yml`
+----
+grails:
+    plugin:
+        springsecurity:
+            securityConfigType: InterceptUrlMap
+----
+
+Then define the URL mappings. In `application.groovy`:
 
 [source,groovy]
-.Listing {counter:listing}. Example `grails.plugin.springsecurity.interceptUrlMap`
+.Listing {counter:listing}. Example `interceptUrlMap` in `application.groovy`
 ----
 grails.plugin.springsecurity.interceptUrlMap = [
    [pattern: '/',               access: ['permitAll']],
@@ -51,10 +62,35 @@ grails.plugin.springsecurity.interceptUrlMap = [
 ]
 ----
 
-and add any custom mappings as needed, e.g.
+Or equivalently in `application.yml`:
+
+[source,yaml]
+.Listing {counter:listing}. Example `interceptUrlMap` in `application.yml`
+----
+grails:
+    plugin:
+        springsecurity:
+            interceptUrlMap:
+                - { pattern: '/',               access: ['permitAll'] }
+                - { pattern: '/error',          access: ['permitAll'] }
+                - { pattern: '/index',          access: ['permitAll'] }
+                - { pattern: '/index.gsp',      access: ['permitAll'] }
+                - { pattern: '/shutdown',       access: ['permitAll'] }
+                - { pattern: '/assets/**',      access: ['permitAll'] }
+                - { pattern: '/**/js/**',       access: ['permitAll'] }
+                - { pattern: '/**/css/**',      access: ['permitAll'] }
+                - { pattern: '/**/images/**',   access: ['permitAll'] }
+                - { pattern: '/**/favicon.ico', access: ['permitAll'] }
+                - { pattern: '/login',          access: ['permitAll'] }
+                - { pattern: '/login/**',       access: ['permitAll'] }
+                - { pattern: '/logout',         access: ['permitAll'] }
+                - { pattern: '/logout/**',      access: ['permitAll'] }
+----
+
+Add any custom mappings as needed, e.g.
 
 [source,groovy]
-.Listing {counter:listing}. Custom `interceptUrlMap` mappings
+.Listing {counter:listing}. Custom `interceptUrlMap` mappings in `application.groovy`
 ----
 grails.plugin.springsecurity.interceptUrlMap = [
    ...
@@ -63,6 +99,17 @@ grails.plugin.springsecurity.interceptUrlMap = [
 ]
 ----
 
+[source,yaml]
+.Listing {counter:listing}. Custom `interceptUrlMap` mappings in `application.yml`
+----
+grails:
+    plugin:
+        springsecurity:
+            interceptUrlMap:
+                - { pattern: '/secure/**',  access: ['ROLE_ADMIN'] }
+                - { pattern: '/finance/**', access: ['ROLE_FINANCE', 'IS_AUTHENTICATED_FULLY'] }
+----
+
 When using this approach, make sure that you order the rules correctly. The first applicable rule is used, so for example if you have a controller that has one set of rules but an action that has stricter access rules, e.g.
 
 [source,groovy]

plugin-core/docs/src/docs/requestMappings/securedAnnotations.adoc

@@ -145,18 +145,73 @@ class Thing {
 
 ==== controllerAnnotations.staticRules
 
-You can also define "`static`" mappings that cannot be expressed in the controllers, such as '/pass:[**]' or for JavaScript, CSS, or image URLs. Use the `controllerAnnotations.staticRules` property, for example:
+You can also define "`static`" mappings that cannot be expressed in the controllers, such as '/pass:[**]' or for JavaScript, CSS, or image URLs. Use the `controllerAnnotations.staticRules` property.
+
+In `application.groovy`:
 
 [source,groovy]
+.Listing {counter:listing}. Static rules in `application.groovy`
 ----
 grails.plugin.springsecurity.controllerAnnotations.staticRules = [
-   ...
    [pattern: '/js/admin/**',   access: ['ROLE_ADMIN']],
    [pattern: '/someplugin/**', access: ['ROLE_ADMIN']]
 ]
 ----
 
-This example maps all URLs associated with `SomePluginController`, which has URLs of the form `/somePlugin/...`, to `ROLE_ADMIN`; annotations are not an option here because you would not edit plugin code for a change like this.
+Or equivalently in `application.yml`:
+
+[source,yaml]
+.Listing {counter:listing}. Static rules in `application.yml` (flow mapping)
+----
+grails:
+    plugin:
+        springsecurity:
+            controllerAnnotations:
+                staticRules:
+                    - { pattern: '/js/admin/**',   access: ['ROLE_ADMIN'] }
+                    - { pattern: '/someplugin/**', access: ['ROLE_ADMIN'] }
+----
+
+Block mapping syntax also works:
+
+[source,yaml]
+.Listing {counter:listing}. Static rules in `application.yml` (block mapping)
+----
+grails:
+    plugin:
+        springsecurity:
+            controllerAnnotations:
+                staticRules:
+                    - pattern: '/js/admin/**'
+                      access:
+                          - ROLE_ADMIN
+                    - pattern: '/someplugin/**'
+                      access:
+                          - ROLE_ADMIN
+----
+
+This example maps all URLs associated with `SomePluginController`, which has URLs of the form `/someplugin/...`, to `ROLE_ADMIN`; annotations are not an option here because you would not edit plugin code for a change like this.
+
+[IMPORTANT]
+====
+The `staticRules` value must be a *List* of Maps. A common YAML mistake is omitting the `-` list indicator, which produces a single Map instead:
+
+[source,yaml]
+.Listing {counter:listing}. Incorrect - single Map instead of List of Maps
+----
+# WRONG - this is a Map, not a List of Maps
+grails:
+    plugin:
+        springsecurity:
+            controllerAnnotations:
+                staticRules:
+                    pattern: '/**'
+                    access:
+                        - permitAll
+----
+
+This will fail with: "`Static rules defined as a Map are not supported; must be specified as a List of Maps`". Each rule must be prefixed with `-` to create a list entry.
+====
 
 [NOTE]
 ====