add documentation (openapi-processor/openapi-processor-base#290)

Author: hauner

docs/modules/ROOT/pages/processor/bean-validation.adoc

@@ -1,6 +1,80 @@
 = Bean Validation
 include::partial$links.adoc[]
 
+== supported target classes
+
+=== avoiding compilation errors
+
+[.badge .badge-since]+since 2022.6+
+
+Each bean-validation annotations has a limited number of supported classes that can be annotated by it. For example, `jakarta.validation.constraints.DecimalMin` does only support number-like classes.
+
+If placed on another non-number class compilation will fail.
+
+This can happen if bean-validation is combined with type mapping. A simple example is number representing a year.
+
+An OpenAPI with an integer parameter and bean validation enabled would add `@DecimalMin` & `@DecimalMax` annotations to the parameter in the generated code.
+
+[source,yaml,subs=attributes+]
+----
+openapi: 3.1.0
+info:
+  title: drop bean validation annotation if mapped to unsupported type
+  version: 1.0.0
+
+paths:
+  /foo:
+    get:
+      parameters:
+        - in: query
+          name: year
+          schema:
+            type: integer
+            format: year
+            minimum: 1970
+            maximum: 2099
+----
+
+This is an issue if the parameter type is mapped to a different Java type. Since the value is representing a year it makes sense to map it `java.time.Year`.
+
+[source,yaml,subs=attributes+]
+----
+openapi-processor-mapping: v14
+
+options:
+  package-name: generated
+  bean-validation: jakarta
+
+map:
+  types:
+    - type: integer:year => java.time.Year
+----
+
+Adding `@DecimalMin` & `@DecimalMax` to the parameter breaks compilation because both annotations do not support `java.time.Year`.
+
+=== supported custom classes
+
+In case the target type is not recognized automatically (and the annotations are dropped), for example on a custom `java.lang.Number` implementation, it is possible to tell the processor that an annotation is valid on that type.
+
+[source,yaml,subs=attributes+]
+----
+openapi-processor-mapping: v14
+
+options:
+# ...
+
+map:
+# ...
+
+bean-validation:
+  jakarta.validation.constraints.DecimalMin:
+    - other.CustomInteger
+  jakarta.validation.constraints.DecimalMax:
+    - other.CustomInteger
+----
+
+See also xref:processor/configuration.adoc#_bean_validation-map[bean validation] configuration.
+
 == WebFlux
 
 The position of the `@Valid` annotation on reactive types has changed in 2024.2. Until then the `@Valid` was placed on the generic type of the reactive wrapper, like this:

docs/modules/ROOT/pages/processor/configuration.adoc

@@ -40,7 +40,8 @@ compatibility:
   bean-validation-valid-on-reactive: false
   identifier-word-break-from-digit-to-letter: false
   identifier-prefix-invalid-enum-start: false
-
+bean-validation:
+   # bean-validation annotation to "custom" classes map
 map:
    # java type mappings
 ----
@@ -533,6 +534,26 @@ keep the pre-2024.2 behavior. See xref:processor/bean-validation.adoc[Bean Valid
 
 *Invalid characters* (e.g. numbers or underscore) at the start of enum values are prefixed with `"V"` (for value) to generate valid java identifiers. The old behaviour (pre-2025.4.1) was to strip the invalid start characters.
 
+[#_bean_validation-map]
+== bean-validation: ([.badge .badge-since]+since 2022.6+)
+
+Opt-In for custom classes that are supported by specific bean-validation annotations.
+
+This is a simple map of bean-validation annotation to a list of additionally supported classes.
+
+[source,yaml,subs=attributes+]
+----
+openapi-processor-mapping: {var-mapping-version}
+
+bean-validation:
+  jakarta.validation.constraints.DecimalMin:
+    - my.custom.Integer
+  jakarta.validation.constraints.DecimalMax:
+    - my.custom.Integer
+----
+
+See xref:processor/bean-validation.adoc[Bean Validation] for an explanation when this may be needed.
+
 == map:
 
 Using type mapping, we can tell the processor to map types (schemas) from an `openapi.yaml` description to a specific existing java type instead of generating a model class from the source OpenAPI type.

docs/modules/ROOT/partials/vars.adoc

@@ -1,2 +1,2 @@
-:var-mapping-version: v13
+:var-mapping-version: v14
 :var-openapi-version: 3.1.0