update docs

Author: hauner

docs/modules/ROOT/pages/mapping/annotation.adoc

@@ -24,13 +24,62 @@ type: {source type} @ {annotation type}
 
 * **type** is required.
 
-** **{source type}** is the type name used in the OpenAPI description and names the type that should
-receive the additional annotation.
+** **{source type}** is the type name used in the OpenAPI description and names the type that should receive the additional annotation. This can be a **{type}:{format}** combination like `string:uuid`.
 
 ** **{annotation type}** is the fully qualified class name of the java annotation type. It may have parameters (see example below).
 
 The link:{oap-samples}[samples project] has a small example using annotation mappings similar to the one described below.
 
+== combining annotation mapping and type mapping
+
+[.badge .badge-since]+since 2023.1+
+
+Previously an annotation mapping was lost if the type was mapped at the same time to an existing class. It will now add the annotation to the existing class if possible.
+
+Assume the following mapping:
+
+[source,yaml]
+----
+openapi-processor-mapping: v3
+
+options:
+
+map:
+  types:
+    - type: Foo => openapiprocessor.MappedFoo
+    - type: Foo @ annotation.Bar  # <1>
+
+  parameters:
+     - type: Foo @ annotation.Bar # <2>
+----
+
+`MappedFoo` is a class that is not generated. Adding an annotation at the parameter level works as expected (mapping `<2>`).  But it is not possible to add the `Bar` annotation directly at the class (mapping `<1>`) like it is possible on a generated class:
+
+[source,java]
+----
+@Bar
+@Generated
+public class Foo {
+    // ....
+}
+----
+
+instead, openapi-processor will add it on any `MappedFoo` property used in the generated model classes:
+
+[source,java]
+----
+@Generated
+public class FooBar {
+
+    @Bar
+    @JsonProperty("foo")
+    private MappedFoo foo;
+
+     // ....
+}
+----
+
+
 == mapping example
 
 Given the following OpenAPI description, that describe two (echo like) endpoints that receive an object via post and return the same object. In the mapping file we add a custom bean validation annotation. It checks the sum of both properties in `Foo` and `Bar`.
@@ -132,7 +181,7 @@ map:
 
 The `Sum` annotation in the example is a custom bean validation but the feature itself is not limited to bean validation.
 
-<1> use `v2.1` as the mapping version to avoid validation warnings in the mapping file.
+<1> use `v2.1` (or later) as the mapping version to avoid validation warnings in the mapping file.
 <2> the `Bar` mapping is using a global type annotation mapping, so the annotation is added to the generated `Bar` class.
 <3> the `Foo` mapping adds the annotation to the parameter of the endpoint methods that use `Foo`.
 <4> this is a list of examples that shows annotation parameters.

docs/modules/ROOT/pages/mapping/structure.adoc

@@ -1,33 +1,30 @@
 = type mapping structure
 include::partial$links.adoc[]
 
-The type mapping is part of the mapping yaml (see xref:processor/configuration.adoc[Configuration])
-and configured under the `map` key. The `map` key contains multiple sections to define the different
-kinds of type mappings.
+The type mapping is part of the mapping yaml (see xref:processor/configuration.adoc[Configuration]) and configured under the `map` key. The `map` key contains multiple sections to define the different kinds of type mappings.
 
 All sections are optional.
 
-== type mapping structure (v2)
+== type mapping structure
 
 //[.badge .badge-since]+since 1.0.0.M15+
 
-This is the preferred format for the mapping. It is simpler than the previous format and uses fewer
-keywords.
-
 [IMPORTANT]
 ====
-To use the new format the mapping file needs the following key on the top-level. Best place is the
-first line of the `mapping.yaml` file.
+The mapping file needs the following key on the top-level. Best place is the first line of the `mapping.yaml` file.
 
 [source,yaml]
 ----
-openapi-processor-mapping: v2
+openapi-processor-mapping: v3
 ----
 ====
 
+The version increases from time to time when openapi-processor requires a new or changed configuration. In case the version changes it is mentioned in the release notes.
+
 
-To map a source type to a destination type it is using an `=>` arrow as *mapping operator* instead
-of individual keywords:
+=== basic mapping
+
+To map a source type to a destination type it is using an `=>` arrow as *mapping operator* instead of individual keywords:
 
 [source,yaml]
 ----
@@ -36,6 +33,8 @@ some-key: {source type} => {target type}
 
 ----
 
+=== full structure
+
 The full structure of the mapping looks like this (a real mapping file will usually use just a few of the possible keys):
 
 [source,yaml]
@@ -56,8 +55,12 @@ map:
 
   # list of global mappings
   types:
+    # replace source type with the given target type
     - type: {source type}  =>  {target type}
 
+    # add an extra annotation to the source type
+    - type: {source type}  @  {target type}
+
   # list of global parameter mappings
   parameters:
     - name: {parameter name}  =>  {target type}
@@ -94,8 +97,12 @@ map:
 
       # list of path specific mappings
       types:
+        # replace source type with the given target type
         - from: {source type}  =>  {target type}
 
+        # add an extra annotation to the source type
+        - type: {source type}  @  {target type}
+
       # list of path specific parameter mappings
       parameters:
         - name: {parameter name}  =>  {target type}
@@ -124,8 +131,4 @@ The structure below `paths` is similar to an OpenAPI yaml file to make it easier
 
 == json schema
 
-Some IDEs support json schemas to provide editing support (auto completion & validation) for text based files. To support this openapi-processor has a link:{json-schema}[json schema] for the v2 mapping format.
-
-== type mapping structure (v1)
-
-This format of the mapping ist still available but should not be used anymore.
+Some IDEs support json schemas to provide editing support (auto-completion & validation) for text based files. To support this, openapi-processor provides json schemas for the mapping formats at link:{json-schema-site}[`https://openapiprocessor.io/schemas/mapping/mapping-v{version}.json`].

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

@@ -8,13 +8,13 @@ A mapping yaml looks like this:
 
 [source,yaml]
 ----
-openapi-processor-mapping: v2
+openapi-processor-mapping: v3
 
 options:
   package-name: io.openapiprocessor.sample
   model-name-suffix: Resource
   one-of-interface: true
-  bean-validation: true
+  bean-validation: jakarta
   generated-date: true
   format-code: false
   javadoc: true
@@ -23,12 +23,11 @@ map:
    # java type mappings
 ----
 
-The only required option is `package-name`.All other options or the type mappings are optional.
+The only required option is `package-name`. All other options or the type mappings are optional.
 
 == options:
 
-* `package-name`: (**required**) the root package name of the generated interfaces & models.The
-package folder tree will be created inside the `targetDir` (see xref:gradle.adoc[using gradle]).
+* `package-name`: (**required**) the root package name of the generated interfaces & models.The  package folder tree will be created inside the `targetDir` (see xref:gradle.adoc[using gradle]).
 +
 Interfaces and models will be generated into the `api` and `model` subpackages of `package-name`.
 +
@@ -37,8 +36,14 @@ Interfaces and models will be generated into the `api` and `model` subpackages o
 
 * `model-suffix-name` (**optional**, default is empty). See xref:_model_name_suffix[below].
 
-* `bean-validation` (**optional**, `true` or `false`) enables generation of bean validation
-annotations. Default is `false`. See link:{bean-validation}[Bean Validation Specification, window="_blank"].
+* `bean-validation` (**optional**, `true` or `false`, `javax`, `jakarta`) enables generation of bean validation annotations. Default is `false`. See link:{bean-validation}[Bean Validation Specification, window="_blank"].
++
+With the [.badge .badge-since]+2023.1+ releases this key allows two new values to handle the package name change from bean validation v2 to v3 (`javax` => `jakarta`).
+
+** `false`: disables bean validation annotations
+** `true`: enables bean validation annotations v2, with `javax` package name
+** `javax`: enables bean validation annotations v2, with `javax` package name
+** `jakarta`: enables bean validation annotations v3, with `jakarta` package name
 
 * `javadoc` (**optional**, `true` or `false`) enables generation of JavaDoc comments from the OpenAPI `description` s on the API interfaces and model pojos.Default is `false`.This is still experimental.
 
@@ -141,9 +146,6 @@ public class BarResource { // <4>
 <4> the class name of the `BarResource` is identical to the original schema name. Since the existing suffix is equal to `model-name-suffix` it is ignored. Otherwise, This prevents funny class names like `BarResourceResource`.
 
 
-
-
-
 == map:
 
 Using type mapping we can tell the processor to map types (schemas) from an `openapi.yaml`

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

@@ -13,9 +13,9 @@ A call to the `/ping` endpoint will simply respond with a plain text string resu
 [source,yaml]
 ----
 openapi: 3.0.2
-    info:
-      title: openapi-processor-spring sample
-      version: 1.0.0
+info:
+    title: openapi-processor-spring sample
+    version: 1.0.0
 
     paths:
       /ping:

docs/modules/ROOT/partials/links.adoc

@@ -16,6 +16,7 @@
 :badge-central: https://img.shields.io/maven-central/v/io.openapiprocessor/openapi-processor-spring?label=Maven%20Central
 :oapc-inttests: https://github.com/openapi-processor/openapi-processor-core/tree/master/src/testInt/resources/tests
 :json-schema: https://github.com/openapi-processor/openapi-processor-core/blob/master/src/main/resources/mapping/v2/mapping.yaml.json
+:json-schema-site: https://openapiprocessor.io/schemas/mapping/mapping-v3.json
 
 //
 // other external links