#143, updated documentation

Author: hauner

docs/modules/ROOT/nav.adoc

@@ -20,6 +20,7 @@
 ** xref:mapping/result-style.adoc[Global Result Style]
 ** xref:mapping/single-multi.adoc[Global Single & Multi Mapping]
 ** xref:mapping/endpoint.adoc[Endpoint Mapping]
+** xref:mapping/annotation.adoc[Additional Annotation]
 ** xref:mapping/null.adoc[Null Mapping]
 ** xref:mapping/package-name.adoc[package-name Mapping]
 * xref:gradle.adoc[Gradle Integration]

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

@@ -0,0 +1,141 @@
+= annotations
+
+It is possible to add additional annotations to a `source type`. Currently, this is *ONLY* available for endpoint method parameters. Since a `requestBody` is passed as parameter the mapping will work fot it too.
+
+== additional parameter annotations
+
+To add an annotation to a `source type` (i.e. an OpenAPI type) parameter the mapping supports an _annotation type mapping_. It is defined like below, and it should be added to the `map/parameters` section in the mapping.yaml.
+
+It is also available as an endpoint (method) mapping to restrict the mapping to a specific endpoint. This will go to the `map/paths/<endpoint path>/parameters` section in the mapping.yaml.
+
+The annotation type mapping is similar to other mappings and is defined like this:
+
+[source,yaml]
+----
+- 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.
+
+** **{annotation type}** is the fully qualified class name of the java annotation type. It may have parameters (see example below).
+
+
+== mapping example
+
+Given the following OpenAPI description:
+
+[source,yaml]
+----
+openapi: 3.0.3
+info:
+  title: openapi-processor-spring sample api
+  version: 1.0.0
+
+paths:
+  /foo:
+    get:
+      tags:
+        - foo
+      summary: annotation mapping example.
+      description: a simple endpoint where an annotation mapping is used
+      parameters:
+        - in: query
+          name: foo
+          schema:
+            $ref: '#/components/schemas/Foo'
+      responses:
+        '204':
+          description: no content
+
+  /foo-body:
+    post:
+      tags:
+        - foo
+      summary: annotation mapping example.
+      description: a simple endpoint where an annotation mapping is used
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Foo'
+        required: true
+      responses:
+        '204':
+          description: no content
+
+components:
+  schemas:
+    Foo:
+      type: object
+      properties:
+        bar:
+          type: string
+----
+
+and a `mapping.yaml` with annotation type mappings. This one uses endpoint specific annotation mappings to show it with and without parameters.
+
+[source,yaml]
+----
+openapi-processor-mapping: v2
+
+options:
+  package-name: io.openapiprocessor.openapi
+
+map:
+
+  paths:
+    /foo:
+      get:
+        parameters:
+          - type: Foo @ annotation.Bar()
+
+      post:
+        parameters:
+          - type: Foo @ annotation.Bar(bar = "foo", level = 42)
+          # this does work too
+          # - type: Foo @ annotation.Bar
+          # - type: Foo @ annotation.Bar()
+          # - type: Foo @ annotation.Bar("bar")
+----
+
+To show the result with and without parameters the mappings are added only to the get/post http methods of the endpoint. We could call this an _endpoint http method annotation type mapping_ ;-).
+
+Here is the generated interface:
+
+[source,java]
+----
+package io.openapiprocessor.openapi.api;
+
+import annotation.Bar;
+import io.openapiprocessor.openapi.model.Foo;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+
+public interface FooApi {
+
+    /**
+     * annotation mapping example.
+     *
+     * <p>a simple endpoint where an annotation mapping is used ona query parameter
+     */
+    @GetMapping(path = "/foo")
+    void getFoo(@Bar Foo foo);
+
+    /**
+     * annotation mapping example.
+     *
+     * <p>a simple endpoint where an annotation mapping is used on the request body
+     */
+    @PostMapping(
+            path = "/foo",
+            consumes = {"application/json"})
+    void postFoo(@RequestBody @Bar(bar = "foo", level = 42) Foo body);
+
+}
+
+----
+

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

@@ -35,6 +35,9 @@ map:
         # add a (usually technical) parameter that is not described in the OpenAPI
         - add: {parameter name}  =>  {target type}
 
+        # add an extra annotation to parameters of type source type
+        - type: {source type}  @  {annotation type}
+
       # list of path specific content mappings, mapped by content type
       responses:
         - content: {content type}  =>  {target type}
@@ -64,6 +67,9 @@ map:
         # add a (usually technical) parameter that is not described in the OpenAPI
         - add: {parameter name}  =>  {target type}
 
+        # add an extra annotation to parameters of type source type
+        - type: {source type}  @  {annotation type}
+
       # list of path specific content mappings, mapped by content type
       responses:
         - content: {content type}  =>  {target type}

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

@@ -65,6 +65,9 @@ map:
     # add a (usually technical) parameter that is not described in the OpenAPI
     - add: {parameter name}  =>  {target type}
 
+    # add an extra annotation to parameters of type source type
+    - type: {source type}  @  {annotation type}
+
   # list of global content mappings, mapped by content type
   responses:
     - content: {content type}  =>  {target type}
@@ -100,6 +103,9 @@ map:
         # add a (usually technical) parameter that is not described in the OpenAPI
         - add: {parameter name}  =>  {target type}
 
+        # add an extra annotation to parameters of type source type
+        - type: {source type}  @  {annotation type}
+
       # list of path specific content mappings, mapped by content type
       responses:
         - content: {content type}  =>  {target type}