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

hauner · hauner · commit 4494ae5d31be · 2025-12-31T16:51:43.000+01:00
diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc
@@ -27,6 +27,7 @@
 ** xref:mapping/single-multi.adoc[Global Single & Multi Mapping]
 ** xref:mapping/endpoint.adoc[Endpoint Mapping]
 ** xref:mapping/annotation.adoc[Annotation Mapping]
+** xref:mapping/interface.adoc[Interface Mapping]
 ** xref:mapping/extension.adoc[Extension Mapping]
 ** xref:mapping/null.adoc[Null Mapping]
 ** xref:mapping/package-name.adoc[package-name Mapping]
diff --git a/docs/modules/ROOT/pages/mapping/index.adoc b/docs/modules/ROOT/pages/mapping/index.adoc
@@ -2,14 +2,29 @@
 
 Type mapping is an important feature of the processor and helps it to create the expected code.
 
-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.
+Using type mapping, we can tell the processor to map a type (or schema) from an openapi.yaml description to a specific existing java type instead of generating a model class from the source OpenAPI type.
 
-This can be a type created by us or a type from a framework. For example, to map paging parameters and result to the Spring types `Page<>` & `Pageable`.
+This can be a type created by ourselves or a type from a framework. For example, to map paging parameters and result to the Spring types `Page<>` & `Pageable`.
 
 It can also be used to map the OpenAPI `array` type to a different java collection type if the default does not fulfill our needs.
 
 Type mapping is very flexible. It is possible to define the mapping globally, globally for a specific response or parameter or limited to a specific endpoint or even http method for an endpoint.
 
-Type mapping also supports (nested) generic parameters to the target type. Multiple levels.
+Type mapping also supports (nested) generic parameters of the target type. Multiple levels.
 
+[NOTE]
+====
 Type mapping works best with named schemas (i.e., schemas `$ref` erenced by their name).
+====
+
+openapi-processor offers two other kinds of type mappings that _modify_ the generated target type instead of _mapping_ to an existing type.
+
+== annotation type mapping
+
+annotation mapping adds a given annotation to the generated target type.
+
+== interface type mapping
+
+interface mapping adds the given interface to the `implements` list of the generated target type.
+
+Since the processor can't provide implementations for the interface methods, the interface should be a marker interface or overlap with the generated target type.
diff --git a/docs/modules/ROOT/pages/mapping/interface.adoc b/docs/modules/ROOT/pages/mapping/interface.adoc
@@ -0,0 +1,158 @@
+= Interface mapping
+include::partial$links.adoc[]
+include::partial$vars.adoc[]
+
+[.badge .badge-since]+since 2026.1+
+
+It is possible to let the generated `target type` implement an interface. Currently, this is available as
+
+* global _interface type mapping_:
++
+it adds a given interface to the `implements` list of the *model class* generated for the `source type`. +
+ +
+
+* global & endpoint parameter _interface mapping_:
++
+it adds an interface to a *parameter* of the `source type` (this includes request body parameters).
+
+The global interface mapping should be added to the `map/types` or `map/parameters` section in the mapping.yaml.
+
+The endpoint (http method) mapping restricts the mapping to a specific endpoint. This will go to the `map/paths/<endpoint path>/parameters` section in the mapping.yaml.
+
+The interface mapping is similar to other mappings and is defined like this:
+
+[source,yaml]
+----
+type: {source type} =+ {interface type}
+----
+
+or alternatively
+
+[source,yaml]
+----
+type: {source type} implement {interface type}
+----
+
+
+* **type** is required.
+
+** **{source type}** is the type name used in the OpenAPI description and also the name of the generated target type. The target type has to be a Java type that accepts an `implements` clause.
+
+** **{interface type}** is the fully qualified class name of the java interface type. It may have parameters (see the examples below).
+
+Here are a few examples:
+
+[source,yaml]
+----
+ - type: Foo =+ java.io.Serializable
+ - type: Foo implement java.io.Serializable
+ - type: Foo implement some.Interface<java.lang.String>
+----
+
+*`object` source type*
+
+it is also possible to add an interface to **all** generated schema/model classes using a single interface mapping:
+
+[source,yaml]
+----
+ - type: object =+ {interface type}
+----
+
+The `object` string represents **all** generated object classes (i.e., schema/model classes) and will add the given interface to all of them.
+
+For example, a mapping like this:
+
+[source,yaml]
+----
+map:
+  types:
+    - type: object =+ java.io.Serializable
+----
+
+[source,java]
+----
+import java.io.Serializable;
+
+@Generated(...)
+public class Foo implements Serializable {
+   ...
+}
+----
+
+The link:{oap-samples}[samples project] has a small example using annotation mappings.
+
+== combining interface mapping and type mapping
+
+Type mapping replaces the generated class with an *existing* Java type. It is not possible to add an interface to an existing class.
+
+== mapping example
+
+The following OpenAPI description describes a simple endpoint which returns a Foo schema. In the mapping file we add an interface mapping for `java.io.Serializable`. This will generate a `Foo` record (or class) that implements the interface.
+
+[source,yaml,subs=attributes+]
+----
+openapi: {var-openapi-version}
+info:
+  title: interface mapping
+  version: 1.0.0
+
+paths:
+
+  /foo:
+    get:
+      responses:
+        '200':
+          description: the foo result
+          content:
+            application/json:
+                schema:
+                  $ref: '#/components/schemas/Foo'
+
+components:
+  schemas:
+
+    Foo:
+      type: object
+      properties:
+        foo:
+          type: string
+----
+
+and a `mapping.yaml` with annotation type mappings:
+
+[source,yaml,subs=attributes+]
+----
+openapi-processor-mapping: {var-mapping-version} # <1>
+
+options:
+  package-name: io.openapiprocessor.openapi
+  model-type: record  # generate record instead of pojo
+
+map:
+  types:
+    - type: Foo =+ java.io.Serializable # <1>
+----
+
+<1> the interface mapping
+
+Here is the generated `Foo` record:
+
+[source,java]
+----
+package io.openapiprocessor.samples.model;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+import io.openapiprocessor.samples.FooAnnotation;
+import io.openapiprocessor.samples.support.Generated;
+import jakarta.validation.Valid;
+import jakarta.validation.constraints.Size;
+import java.io.Serializable;
+import java.util.UUID;
+
+@Generated(value = "openapi-processor-spring")
+public record Foo(@JsonProperty("foo") String foo)
+implements Serializable { // <1>
+}
+----
+
+<1> it implements the given interface
diff --git a/docs/modules/ROOT/pages/mapping/structure.adoc b/docs/modules/ROOT/pages/mapping/structure.adoc
@@ -2,7 +2,7 @@
 include::partial$links.adoc[]
 include::partial$vars.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 mapping.
 
 All sections are optional.
 
@@ -12,7 +12,7 @@ All sections are optional.
 
 [IMPORTANT]
 ====
-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. The best place is the first line of the `mapping.yaml` file.
 
 [source,yaml,subs=attributes+]
 ----
@@ -23,9 +23,9 @@ openapi-processor-mapping: {var-mapping-version}
 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.
 
 
-=== basic mapping
+=== basic type mapping
 
-To map a source type to a destination type, it is using an `=>` arrow as a *mapping operator* instead of individual keywords:
+To *map* a source type to a destination type, use the *mapping operator*: `=>`
 
 [source,yaml]
 ----
@@ -34,7 +34,63 @@ some-key: {source type} => {target type}
 
 ----
 
-*source type* is usually a name (or type) from the OpenAPI description and *target type* is usually a java type.
+Usually, *source type* is a name (or type) from the OpenAPI description, and *target type* is a java type.
+
+[.badge .badge-since]+since 2026.1+
+
+Alternatively, if the operator is too cryptic, it is possible to use the *map* keyword instead of the operator.
+
+[source,yaml]
+----
+
+some-key: {source type} map {target type}
+
+----
+
+
+=== basic annotation mapping
+
+To *annotate* the generated target type, use the *annotation operator*: `@`
+
+[source,yaml]
+----
+
+some-key: {source type} @ {target type}
+
+----
+
+[.badge .badge-since]+since 2026.1+
+
+Alternatively, if the operator is too cryptic, it is possible to use the *annotate* keyword instead of the operator.
+
+[source,yaml]
+----
+
+some-key: {source type} annotate {target type}
+
+----
+
+=== basic interface mapping
+
+[.badge .badge-since]+since 2026.1+
+
+To let the generated target type *implement* an interface, use the *interface operator*: `=+`
+
+[source,yaml]
+----
+
+some-key: {source type} =+ {target type}
+
+----
+
+Alternatively, if the operator is too cryptic, it is possible to use the *implement* keyword instead of the operator.
+
+[source,yaml]
+----
+
+some-key: {source type} implement {target type}
+
+----
 
 === full structure
 
@@ -68,6 +124,9 @@ map:
     # add an extra annotation to the source type
     - type: {source type}  @  {target type}
 
+    # add an extra (marker) interface to the source type
+    - type: {source type}  =+  {target type}
+
   # list of global schema mappings
   schemas:
     # add an extra annotation to the source type, but only on object properties
@@ -83,6 +142,9 @@ map:
     # add an extra annotation to parameters of the source type
     - type: {source type}  @  {annotation type}
 
+    # add an extra (marker) interface to the source type
+    - type: {source type}  =+  {target type}
+
   # list of global content mappings, mapped by content type
   responses:
     - content: {content type}  =>  {target type}
@@ -121,6 +183,9 @@ map:
         # add an extra annotation to the source type
         - type: {source type}  @  {target type}
 
+        # add an extra (marker) interface to the source type
+        - type: {source type}  =+  {target type}
+
       # list of path-specific parameter mappings
       parameters:
         - name: {parameter name}  =>  {target type}
@@ -131,6 +196,9 @@ map:
         # add an extra annotation to parameters of source type
         - type: {source type}  @  {annotation type}
 
+        # add an extra (marker) interface to the source type
+        - type: {source type}  =+  {target type}
+
       # list of path-specific content mappings, mapped by content type
       responses:
         - content: {content type}  =>  {target type}
