Simplify API Key YAML configuration and JavaDoc; add collapsed attr… (#2808)

* Simplify API Key YAML configuration and JavaDoc; add `collapsed` attribute to MCElement annotations.

* docs(api-key): update YAML configuration and examples, refine migration guide

- Replaced `headerExtractor` and `queryParamExtractor` with simplified `header` and `query` formats in YAML.
- Updated Migration Guide and examples to reflect the new configuration styles for ApiKey extractors.
- Added new configuration formats to the list of supported elements.

* Simplified CORS interceptor Javadoc examples by removing `<pre><code>` tags.

* fixes

* fixes

---------

Co-authored-by: Christian Gördes <118011644+christiangoerdes@users.noreply.github.com>
Co-authored-by: Christian Gördes <christian.goerdes@outlook.de>

Author: predic8

core/src/main/java/com/predic8/membrane/core/interceptor/apikey/extractors/ApiKeyHeaderExtractor.java

@@ -30,13 +30,11 @@
  * @yaml <pre><code>
  * apiKey:
  *  extractors:
- *    - header: {} # default: X-Api-Key
- *    - header:
- *        name: Authorization # custom header name
+ *    - header: x-key # custom header name
  * </code></pre>
  * @topic 3. Security and Validation
  */
-@MCElement(name="header", id = "headerExtractor", component = false)
+@MCElement(name="header", id = "headerExtractor", component = false, collapsed = true)
 public class ApiKeyHeaderExtractor implements ApiKeyExtractor{
 
     private HeaderName headerName = new HeaderName("X-Api-Key");
@@ -54,9 +52,9 @@ public Optional<LocationNameValue> extract(Exchange exc) {
 
     /**
      * @description The HTTP header name to check for an API key.
-     * @default X-Api-Key
      * @example Authorization
      */
+   @Required
     @MCAttribute(attributeName = "name")
     public void setHeaderName(String headerName) {
         if(!headerName.isBlank()) this.headerName = new HeaderName(headerName);

core/src/main/java/com/predic8/membrane/core/interceptor/apikey/extractors/ApiKeyQueryParamExtractor.java

@@ -33,13 +33,11 @@
  * @yaml <pre><code>
  * - apiKey:
  *     extractors:
- *       - query: {} # default: api-key
- *       - query:
- *           name: auth # custom query param name
+ *       - query: apikey # custom query param name
  * </code></pre>
  * @topic 3. Security and Validation
  */
-@MCElement(name = "query", id="queryParamExtractor", component = false)
+@MCElement(name = "query", id="queryParamExtractor", component = false, collapsed = true)
 public class ApiKeyQueryParamExtractor implements ApiKeyExtractor{
 
     private static final Logger log = LoggerFactory.getLogger(ApiKeyQueryParamExtractor.class);
@@ -66,9 +64,9 @@ public Optional<LocationNameValue> extract(Exchange exc) {
 
     /**
      * @description The query parameter name to check for an API key.
-     * @default api-key
      * @example api_key
      */
+    @Required
     @MCAttribute(attributeName = "name")
     public void setParamName(String paramName) {
         this.paramName = paramName;

core/src/main/java/com/predic8/membrane/core/interceptor/cors/CorsInterceptor.java

@@ -243,7 +243,7 @@ public Set<String> getMethods() {
      * @default "" (no additional headers beyond safe headers)
      *
      * @example
-     * <pre><code><cors headers="Authorization,X-Custom-Header,X-Requested-With" /></code></pre>
+     * Authorization,X-Custom-Header,X-Requested-With
      */
     @MCAttribute
     public void setHeaders(String headers) {
@@ -266,7 +266,7 @@ public String getHeaders() {
      * @default "" (expose no additional headers)
      *
      * @example
-     * <pre><code><cors exposeHeaders="X-Total-Count,X-Custom-Info" /></code></pre>
+     * X-Total-Count,X-Custom-Info
      */
     @MCAttribute
     public void setExposeHeaders(String headers) {
@@ -289,10 +289,7 @@ public String getExposeHeaders() {
      * @param credentials true to allow credentials, false to disallow
      * @default false
      *
-     * @example
-     * <pre><code><cors
-     *   origins="https://trusted-app.com"
-     *   credentials="true" /></code></pre>
+     * @example true
      */
     @MCAttribute
     public void setCredentials(boolean credentials) {
@@ -315,8 +312,7 @@ public boolean getCredentials() {
      * @param maxAge maximum cache age in seconds (0 = no caching)
      * @default 5 seconds
      *
-     * @example
-     * <pre><code><cors maxAge="3600" /></code></pre>
+     * @example 3600
      */
     @MCAttribute
     public void setMaxAge(int maxAge) {

distribution/examples/security/api-key/apikey-openapi/apis.yaml

@@ -16,8 +16,7 @@ api:
         # API keys are validated in the OpenAPI validator with validateSecurity: true. See the OpenAPI document for details.
         required: false
         extractors:
-          - header:
-              name: "X-Api-Key"
+          - header: X-Api-Key
       # The API key must be extracted before the OpenAPI validator is called.
       # Normally, the OpenAPI is validated before the flow is executed. By explicitly
       # setting the openapiValidator to this position, the OpenAPI is validated after the apiKey plugin.

distribution/examples/security/api-key/rbac/apis.yaml

@@ -17,8 +17,7 @@ global:
       # But certain scopes allow for additional access rights.
       required: false
       extractors:
-        - header:
-            name: X-Key
+        - header: X-Key
 
 ---
 api:

distribution/examples/security/api-key/simple/apis.yaml

@@ -14,11 +14,11 @@ global:
       extractors:
         # Fetch the API key from header
         # X-Api-Key: demokey
-        - header: {}
+        - header: X-Api-Key
 
         # Fetch key from query
         # GET /foo?api-key=abc123
-        - query: {}
+        - query: api-key
 
 ---
 

distribution/examples/security/jwt/apikey-to-jwt-conversion/apis.yaml

@@ -10,7 +10,7 @@ api:
           - apiKeyFileStore:
               location: demo-keys.txt
         extractors:
-          - header: {}
+          - header: X-Api-Key
     - request:
         - template:
             contentType: application/json

docs/MIGRATION-GUIDE.md

@@ -27,8 +27,8 @@ Remove these elements from your configuration and replace them with modern equiv
 - Return string from script does not set a content type of `text/html` anymore. User has to set the content type manually.
 
 ## ApiKey extractors:
-- Rename `headerExtractor` to `header`
-- Rename `queryParamExtractor` to `query`
+- Replace `headerExtractor: \n    name: <value>` with `header: <value>`
+- Replace `queryParamExtractor: \n    name: <value>` with `query: <value>`
 ```yaml
 # before
 apiKey: 
@@ -41,10 +41,8 @@ apiKey:
 # now 
 apiKey:
   extractors:
-    - header:
-        name: X-API-KEY
-    - query:
-        name: api-key
+    - header: X-API-KEY
+    - query: api-key
 ```
 
 ## fileUserDataProvider
@@ -209,7 +207,7 @@ api:
 ### YAML configuration for Elements with exactly one configurable Attribute
 Some Elements with **exactly one** configurable Attribute can now be configured inline. This **does not** apply to all elements with exactly one configurable Attribute.
 
-The supported elements are: `api.description`, `publicURL`, `headerFilter.include`, `headerFilter.exclude`, `keyTable`, `scopeTable`, `accessControl.allow`, `accessControl.deny`, `counter`, `mutation`
+The supported elements are: `api.description`, `publicURL`, `headerFilter.include`, `headerFilter.exclude`, `keyTable`, `scopeTable`, `accessControl.allow`, `accessControl.deny`, `counter`, `mutation`, `header` (ApiKey extractor), `query` (ApiKey extractor)
 
 #### headerFilter
 ```yaml