#143, updated documentation

Author: hauner

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

@@ -1,12 +1,19 @@
 = annotations
+include::partial$links.adoc[]
 
-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.
+It is possible to add additional annotations to a `source type`. Currently, this is available as
 
-== additional parameter annotations
+* global _annotation type mapping_:
++
+it adds an annotation to the model class generated for the `source type`.
 
-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.
+* global & endpoint parameter _annotation type mapping_:
++
+it adds an annotation to a parameter of the `source type`. Since the request body is passed as parameter the mapping will work for it too.
 
-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.
+It is defined like below, and it should be added to the `map/types` or `map/parameters` section in the mapping.yaml.
+
+It is also available as an endpoint (http 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:
 
@@ -22,96 +29,123 @@ receive the additional annotation.
 
 ** **{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.
 
 == mapping example
 
-Given the following OpenAPI description:
+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`.
 
 [source,yaml]
 ----
-openapi: 3.0.3
+openapi: 3.1.0
 info:
   title: openapi-processor-spring sample api
   version: 1.0.0
 
 paths:
   /foo:
-    get:
+    post:
       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'
+      description: a simple endpoint where an annotation mapping is used on the request body
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Foo'
+        required: true
       responses:
-        '204':
-          description: no content
-
-  /foo-body:
+        '200':
+          description: echo of the source parameter
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Foo'
+
+  /bar:
     post:
       tags:
-        - foo
+        - bar
       summary: annotation mapping example.
-      description: a simple endpoint where an annotation mapping is used
+      description: a simple endpoint where an annotation mapping is used on the request body
       requestBody:
         content:
           application/json:
             schema:
-              $ref: '#/components/schemas/Foo'
+              $ref: '#/components/schemas/Bar'
         required: true
       responses:
-        '204':
-          description: no content
+        '200':
+          description: echo of the source parameter
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Bar'
 
 components:
   schemas:
     Foo:
       type: object
       properties:
-        bar:
-          type: string
+        foo1:
+          type: integer
+          minimum: 0
+        foo2:
+          type: integer
+          minimum: -10
+
+    Bar:
+      type: object
+      properties:
+        bar1:
+          type: integer
+        bar2:
+          type: integer
 ----
 
-and a `mapping.yaml` with annotation type mappings. This one uses endpoint specific annotation mappings to show it with and without parameters.
+and a `mapping.yaml` with annotation type mappings:
 
 [source,yaml]
 ----
 openapi-processor-mapping: v2
 
 options:
   package-name: io.openapiprocessor.openapi
+  javadoc: true
+  format-code: true
+  bean-validation: true
 
 map:
+  types:
+    - type: Bar @ io.openapiprocessor.samples.validations.Sum(24) # <1>
 
-  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")
+  parameters:
+    - type: Foo @ io.openapiprocessor.samples.validations.Sum(value = 42) # <2>
+
+      # this formats do work too <3>
+      # - type: Foo @ annotation.Bar
+      # - type: Foo @ annotation.Bar()
+      # - type: Foo @ annotation.Bar("bar")
+      # - type: Foo @ annotation.Bar(value = "bar", foo = 2)
 ----
 
-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_ ;-).
+The `Sum` annotation in the example is a custom bean validation but the feature itself is not limited to bean validation.
+
+<1> the `Bar` mapping is using a global type annotation mapping, so the annotation is added to the generated `Bar` class.
+<2> the `Foo` mapping adds the annotation to the parameter of the endpoint methods that use `Foo`.
+<3> this is a list of examples that shows annotation parameters. It is nearly java code.
 
-Here is the generated interface:
+Here are the generated interfaces, first the `FooApi`:
 
 [source,java]
 ----
 package io.openapiprocessor.openapi.api;
 
-import annotation.Bar;
 import io.openapiprocessor.openapi.model.Foo;
-import org.springframework.web.bind.annotation.GetMapping;
+import io.openapiprocessor.samples.validations.Sum;
+import javax.validation.Valid;
+import javax.validation.constraints.NotNull;
 import org.springframework.web.bind.annotation.PostMapping;
 import org.springframework.web.bind.annotation.RequestBody;
 
@@ -120,22 +154,114 @@ public interface FooApi {
     /**
      * annotation mapping example.
      *
-     * <p>a simple endpoint where an annotation mapping is used ona query parameter
+     * <p>a simple endpoint where an annotation mapping is used on the request body
+     *
+     * @return echo of the source parameter
      */
-    @GetMapping(path = "/foo")
-    void getFoo(@Bar Foo foo);
+    @PostMapping(
+            path = "/foo",
+            consumes = {"application/json"},
+            produces = {"application/json"})
+    Foo postFoo(@RequestBody @Sum(value = 42) @Valid @NotNull Foo body); // <1>
+
+}
+----
+<1> here is the additional annotation.
+
+and the `BarApi` and the `Bar` class:
+
+[source,java]
+----
+package io.openapiprocessor.openapi.api;
+
+import io.openapiprocessor.openapi.model.Bar;
+import javax.validation.Valid;
+import javax.validation.constraints.NotNull;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+
+public interface BarApi {
 
     /**
      * annotation mapping example.
      *
      * <p>a simple endpoint where an annotation mapping is used on the request body
+     *
+     * @return echo of the source parameter
      */
     @PostMapping(
-            path = "/foo",
-            consumes = {"application/json"})
-    void postFoo(@RequestBody @Bar(bar = "foo", level = 42) Foo body);
+            path = "/bar",
+            consumes = {"application/json"},
+            produces = {"application/json"})
+    Bar postBar(@RequestBody @Valid @NotNull Bar body); // <1>
 
 }
+----
 
+[source,java]
+----
+package io.openapiprocessor.openapi.api;
+
+import io.openapiprocessor.openapi.model.Bar;
+import javax.validation.Valid;
+import javax.validation.constraints.NotNull;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+
+public interface BarApi {
+
+    /**
+     * annotation mapping example.
+     *
+     * <p>a simple endpoint where an annotation mapping is used on the request body
+     *
+     * @return echo of the source parameter
+     */
+    @PostMapping(
+            path = "/bar",
+            consumes = {"application/json"},
+            produces = {"application/json"})
+    Bar postBar(@RequestBody @Valid @NotNull Bar body); // <1>
+
+}
 ----
 
+<1> no annotation here, mapping says it should be on the class:
+
+[source,java]
+----
+package io.openapiprocessor.openapi.model;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+import io.openapiprocessor.samples.validations.Sum;
+
+@Sum(24) // <1>
+public class Bar {
+
+    @JsonProperty("bar1")
+    private Integer bar1;
+
+    @JsonProperty("bar2")
+    private Integer bar2;
+
+    public Integer getBar1() {
+        return bar1;
+    }
+
+    public void setBar1(Integer bar1) {
+        this.bar1 = bar1;
+    }
+
+    public Integer getBar2() {
+        return bar2;
+    }
+
+    public void setBar2(Integer bar2) {
+        this.bar2 = bar2;
+    }
+
+}
+----
+
+<1> and here it is :-)
+

docs/modules/ROOT/partials/links.adoc

@@ -11,6 +11,7 @@
 :oaps-bintray: https://bintray.com/openapi-processor/openapi-processor
 :oap-gradle: https://github.com/openapi-processor/openapi-processor-gradle
 :oap-playground: https://playground.openapiprocessor.io
+:oap-samples: https://github.com/openapi-processor/openapi-processor-samples
 :oap-central: https://search.maven.org/search?q=io.openapiprocessor
 :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