update docs

Author: hauner

docs/modules/ROOT/nav.adoc

@@ -7,6 +7,7 @@
 ** xref:processor/parameter.adoc[Parameter]
 ** xref:processor/requestbody.adoc[Request Body]
 ** xref:processor/response.adoc[Responses]
+** xref:processor/deprecated.adoc[Deprecated]
 ** xref:processor/identifier.adoc[Identifier]
 * xref:mapping/index.adoc[Type Mapping]
 ** xref:mapping/structure.adoc[Type Mapping Structure]

docs/modules/ROOT/pages/index.adoc

@@ -86,12 +86,11 @@ correct code for an endpoint. That way the processor can still be used for all t
 
 - the generated code does not use swagger annotations. There is no need to generate the
 documentation from the code when the code originates from the documentation (i.e. an openapi.yaml).
-+
-NOTE: The generated source code has to be included in a project to compile it. This is easily done
-with the xref:gradle::index.adoc[openapi-processor-gradle] plugin. See xref:gradle.adoc[Using Gradle].
 
-- gradle support via xref:gradle::index.adoc[openapi-processor-gradle] plugin (the plugin is
-currently the only option to run the processor).
+- *maven & gradle support* The plugin docs show how to run a processor and how to add the generated sources to the build.
+
+** xref:maven::index.adoc[openapi-processor-maven] plugin.
+** xref:gradle::index.adoc[openapi-processor-gradle] plugin.
 
 == Releases
 

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

@@ -0,0 +1,134 @@
+= Deprecated items
+
+OpenAPI allows adding `deprecated: true` at several places. openapi-processor-spring translates them to Java's `@Deprecated` annotation.
+
+
+== deprecated endpoint
+
+
+[cols="2*",grid=row,frame=none]
+|===
+a|OpenAPI
+a|Java Code
+
+a|[source,yaml]
+----
+/foo:
+  get:
+    deprecated: true # <1>
+----
+
+a|[source,java]
+----
+@Deprecated // <2>
+@GetMapping("/foo")
+/*...*/ getFoo();
+----
+|===
+
+<1> a deprecated endpoint
+<2> the generated endpoint method with a `@Deprecated` annotation
+
+== deprecated parameter
+
+
+[cols="2*",grid=row,frame=none]
+|===
+a|OpenAPI
+a|Java Code
+
+
+a|[source,yaml]
+----
+/foo:
+  get:
+    parameters:
+      - name: bar
+        deprecated: true # <1>
+        in: query
+        schema:
+          type: string
+----
+a|[source,java]
+----
+@GetMapping("/foo")
+/* ... */ getFoo(@Deprecated String bar); // <2>
+----
+|===
+
+<1> a deprecated parameter
+<2> the generated endpoint method with a `@Deprecated` annotation on the `bar` parameter.
+
+== deprecated schema
+
+[cols="2*",grid=row,frame=none]
+|===
+a|OpenAPI
+a|Java Code
+
+a|[source,yaml]
+----
+Bar:
+  type: object
+  deprecated: true # <1>
+  properties:
+    foobar:
+      type: string
+
+----
+
+a|[source,java]
+----
+@Deprecated // <2>
+public class Bar {
+    /* ... */
+}
+
+----
+|===
+
+<1> a deprecated schema
+<2> the generated model class with a `@Deprecated` annotation.
+
+== deprecated schema property
+
+[cols="2*",grid=row,frame=none]
+|===
+a|OpenAPI
+a|Java Code
+
+a|[source,yaml]
+----
+Bar:
+  type: object
+  properties:
+    foobar:
+      deprecated: true # <1>
+      type: string
+----
+
+a|[source,java]
+----
+public class Bar {
+
+    @Deprecated  // <2>
+    @JsonProperty("foobar")
+    private String foobar;
+
+    @Deprecated // <2>
+    public String getFoobar() {
+        return foobar;
+    }
+
+    @Deprecated // <2>
+    public void setFoobar(String foobar) {
+        this.foobar = foobar;
+    }
+
+}
+
+----
+|===
+
+<1> a deprecated schema property
+<2> the generated model class with `@Deprecated` annotations at the property, getter and setter. (hmm, the annotated property may be a bit too much... )