improved docs

Author: hauner

docs/modules/ROOT/pages/api.adoc

@@ -11,8 +11,8 @@ The following sections describe how to activate & configure **openapi-processor-
 
 == adding the plugin
 
-The [openapi-processor-gradle][oap-gradle] plugin is activated (like any other gradle plugin) in
- the `plugins` configuration:
+To [openapi-processor-gradle][oap-gradle] activate the plugin add it to (like any other gradle
+plugin) the `plugins` configuration:
 
 [source,groovy]
 ----
@@ -26,7 +26,7 @@ plugins {
 == configuring processor-spring
 
 The plugin will add an `openapiProcessor` configuration block that is used to configure the processors.
-Configuration for a specific processor is placed inside it using the processor name as configuration
+Configuration for a specific processor belongs inside it with the processor name as configuration
 block name.
 
 [source,groovy]
@@ -49,11 +49,11 @@ dependency to a configuration in the gradle `dependencies` block. It is given he
 un-wanted side effects on the build dependencies of the project.
 
 * `apiPath`: (**required**) the path to the `openapi.yaml` file and the main input for the
-processor. If set in the top level block it will be used for all configured processors.
+processor. If set in the top-level block it will be used for all configured processors.
 
 * `targetDir`: (**required**) the output folder for generating interfaces & models. This is the
 parent of the `packageName` folder tree. It is recommended to set this to a subfolder of gradle's
-standard `build` directory so it is cleared by the `clean` task and does not pollute the sources
+standard `build` directory, so it is cleared by the `clean` task and does not pollute the `sources`
 directory.
 +
 See <<running processor-spring>> how to include the `targetDir` in compilation & packing.
@@ -70,7 +70,7 @@ yaml. This replaces the `typeMappings` option.
 
 The plugin will add a gradle task `processSpring` to run the processor.
 
-To automatically generate & compile the processor output two additional configurations are required.
+To automatically generate & compile the processor output two additional configurations are necessary.
 
 * the `sourceSets` are extended to include the processor output (assuming a java project):
 +
@@ -86,7 +86,7 @@ sourceSets {
 }
 ----
 
-* and the `compileJava` task gets a dependency on `processSpring` so it runs before compilation
+* and the `compileJava` task gets a dependency on `processSpring`, so it runs before compilation
 (again, assuming a java project):
 +
 [source,groovy]

docs/modules/ROOT/pages/gradle.adoc

@@ -1,10 +1,10 @@
 = map openapi array (globally) to a java collection type
 
-By default the OpenAPI `array` is mapped to a simple java array. That is probably the first thing
+By default, the OpenAPI `array` maps to a simple java array. That is probably the first thing
 you want to change.
 
 To change that default mapping for example to `java.util.Collection` a simple global type mapping
-is required in the xref:mapping/index.adoc[`mapping.yaml`].
+is necessary in the xref:mapping/index.adoc[`mapping.yaml`].
 
 Given the following openapi.yaml fragment:
 

docs/modules/ROOT/pages/howto/global-array-mapping.adoc

@@ -1,7 +1,7 @@
 = using Spring Pageable & Page
 
 The given (lengthy) openapi yaml example describes a pageable api in two variations. The `/page`
-endpoint uses named objects and the second endpoint `/page-inline` uses inline objects to describe
+endpoint uses named objects, and the second endpoint `/page-inline` uses inline objects to describe
 the paging parameters and the page response. We fill focus on the first variation.
 
 [source,yaml]
@@ -91,14 +91,14 @@ components:
 ----
 
 <1> Describing the `Pageable` query parameters `page`, `size` etc in OpenAPI as an `object` lets us
-group the parameters. That tells someone reading the api that they belong together and we can avoid
+group the parameters. That tells a reader of the api that they belong together, and we can avoid
 confusion when there are more query parameters.
 
 <2> Describing the `Page` result is a bit more complicated. OpenAPI does not have generic types
 which we would like to have to define what type is in the content list of the page.
 +
 The best OpenAPI way is to define two objects. The first one describes the common properties of the
-`Page` response and the second one the content list of the page. In this example the `StringContent`
+`Page` response, and the second one the content list of the page. In this example the `StringContent`
 with an array of `string`.
 +
 Using OpenAPIs `allOf` construct we join both objects to describe a complete response that
@@ -185,7 +185,7 @@ generic type of the page `content`.
 
 <3> mapping for the inline version.
 
-Usually you would use the first variation using named objects so they can be re-used on other
+Usually you would use the first variation using named objects, so they can be re-used on other
 endpoints.
 
 Worth mentioning is that the processor will not generate model classes for the openapi types

docs/modules/ROOT/pages/howto/pageable-page-mapping.adoc

@@ -73,14 +73,14 @@ have any effect on other endpoints.
 
 [.badge .badge-since]+since 1.0.0.M6+
 
-It is possible to exclude endpoints from generation so it is possible to create a
-hand written interface for the excluded endpoint.
+It is possible to exclude endpoints from generation to make it easier to provide a hand written
+interface for the excluded endpoint.
 
 Excluding does not completely ignore the endpoint. Instead of generating it into the normal
 interface it is generated to a new interface with `Excluded` attached to its name. Type mappings
 still apply.
 
-That way the the generated code is still available for reference but it can be skipped by not
+That way the generated code is still available for reference, but it can be skipped by not
 implementing the `Excluded` interface.
 
 [source,yaml]

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

@@ -3,7 +3,7 @@
 Global type mapping will replace **any** usage of an OpenAPI type in the api description to the
 given java type.
 
-It is defined like below and it should be added to the `map/types` section in the `mapping.yaml`
+It is defined like below, and it should be added to the `map/types` section in the `mapping.yaml`
 which is a list of global type mappings.
 
 A single global mapping can have the following properties:
@@ -50,7 +50,7 @@ can be mapped to an existing `Book` java type/class by the following mapping:
   to: com.github.hauner.openapi.oap.Book
 ----
 
-It is also possible to use a predefined OpenAPI type as the `from` type of a type mapping:
+It is also possible to use a predefined OpenAPI type in the `from` type of the type mapping:
 
 [source,yaml]
 ----
@@ -60,7 +60,7 @@ It is also possible to use a predefined OpenAPI type as the `from` type of a typ
 
 This tells the processor to us a `java.util.List` instead of the OpenAPI type `array`.
 
-The **generics** parameter is not required in this special case. The processor knows `java.util.List`
+The **generics** parameter is unnecessary in this special case. The processor knows `java.util.List`
 and will automatically use the `items` property of the `array` as the generic type.
 
 [CAUTION]
@@ -69,7 +69,7 @@ and will automatically use the `items` property of the `array` as the generic ty
 assumes  that it is just a schema name and it will only match if there is a schema with the name
 "object".
 * global type mappings do work on OpenAPI inline schemas using the automatically generated name.
-This is not recommended as a small change to the api description could changes the inline name and
+This is not recommended as a small change to the api description could change the inline name and
 break the mapping.
 ====
 
@@ -89,16 +89,16 @@ to the **from** property value separated by a ':' like this:
   to: java.time.ZonedDateTime
 ----
 
-This maps the `string` type with `date-time` format from the default `java.time.OffsetDateTime` to
-`java.time.ZonedDateTime`. `string` without format or `string` with other formats are not affected
-by this mapping.
+This maps the `string` type with a `date-time` format from the default `java.time.OffsetDateTime` to
+`java.time.ZonedDateTime`. The mapping does not affect `string` without a format or `string` with
+other formats.
 
 == mapping with generic types
 
-Type mapping allows to use a target type that has generic parameters. The generic types are defined
+Type mapping allows to use a target type that has generic parameters. The generic types are given
 by the **generics** property of the mapping. **generics** is a list and can contain multiple types.
 
-For example if a `StringPage` schema is defined in the OpenAPI that corresponds to
+For example if a `StringPage` schema in the OpenAPI corresponds to
 `org.springframework.data.domain.Page<java.lang.String>`, it can be mapped to the Spring type by:
 
 [source,yaml]

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

@@ -3,7 +3,7 @@
 Global parameter mapping will replace any usage of an OpenAPI type in the api description based on
  the parameters **name** to the given java type.
 
-It is defined like below and it should be added to the `map/parameters` section in the mapping.yaml
+It is defined like below, and it should be added to the `map/parameters` section in the mapping.yaml
 which is a list of global parameter mappings.
 
 A single global parameter mapping can have the following properties:
@@ -19,11 +19,11 @@ A single global parameter mapping can have the following properties:
 
 * **name** and **to** are required.
 
-* **name** is the name of an endpoint parameter used in the OpenAPI description that should be replaced
-  by **to**.
+* **name** is the name of an endpoint parameter used in the OpenAPI description that should be
+replaced by **to**.
 
 * **to** is the fully qualified class name of the java type that should be used for all endpoint
- parameters of name **name**.
+ parameters of **name**.
 
 * **generics** defines the list of types that should be used as generic type parameters to the
 java type given by **to**.

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

@@ -1,9 +1,9 @@
 = (global) Response mappings
 
-Global response mapping will replace the result type of an endpoint in the api description based on
+Global response mapping will replace the result type of the endpoint in the api description based on
  its **content type** to the given java type.
 
-It is defined like below and it should be added to the `map/responses` section in the mapping.yaml
+It is defined like below, and it should be added to the `map/responses` section in the mapping.yaml
 which is a list of global response mappings.
 
 A single global response mapping can have the following properties:
@@ -19,7 +19,7 @@ A single global response mapping can have the following properties:
 
 * **content** and **to** are required.
 
-* **content** is the name of the content type of an endpoint response that should be replaced
+* **content** is the name of the content type of the endpoint response that should be replaced
   by **to**.
 
 * **to** is the fully qualified class name of the java type that should be used for all endpoint
@@ -33,8 +33,8 @@ java type given by **to**.
 Since the processor will simply match the content type string take care that all responses of this
 content type should really use the same type!
 
-This is probably only useful for vendor content types. Globally mapping the content type for example
- of `application/json` does not look like a good idea.
+This is probably only useful for a vendor content types. Globally mapping the content type for
+example of `application/json` does not look like a good idea.
 ====
 
 == Example
@@ -51,7 +51,8 @@ map:
       to: com.github.hauner.openapi.Something
 ----
 
-and an openapi.yaml with multiple endpoints returning their result as content type `application/vnd.something`
+and an openapi.yaml with multiple endpoints returning their result as content type
+`application/vnd.something`
 
 [source,yaml]
 ----

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

@@ -1,10 +1,10 @@
 = Configuration
 include::partial$links.adoc[]
 
-The configuration of the processor is read from the (mandatory) `mapping.yaml` file. It does contain
+The processor reads the configuration from the (mandatory) `mapping.yaml` file. It does contain
 some  general options and the xref:mapping/index.adoc[mapping] type information.
 
-A mapping yaml looks like this
+A mapping yaml looks like this:
 
 [source,yaml]
 ----
@@ -24,11 +24,11 @@ package  folder tree will be created inside the `targetDir` (see xref:gradle.ado
 +
 Interfaces and models will be generated into the `api` and `model` subpackages of `package-name`.
 +
-** so the final package name of the generated interfaces will be `"$\{package-name\}.api"`
+** so the final package name of the generated interfaces will be `"$\{package-name\}.api"`,
 ** and the final package name of the generated models will be `"$\{package-name\}.model"`
 
 * `bean-validation` (**optional**, `true` or `false`) enables generation of bean validation
-annotations. Defaults to `false`. See link:{bean-validation}[Bean Validation, window="_blank"].
+annotations. Default is `false`. See link:{bean-validation}[Bean Validation, window="_blank"].
 
 == map:
 

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

@@ -4,7 +4,7 @@ A simple path of the OpenAPI description will usually produce a single endpoint
 interface as described in the introduction.
 
 OpenAPI allows us to define more complex apis that behave differently based on the request header.
-For example the following api definition can return its response in different format. As json or as
+For example the following api definition can return its response in different formats. As json or as
 plain text:
 
 [source,yaml]
@@ -85,8 +85,8 @@ public interface Api {
 The apis normal response (status '200') can return the result as json or as plain text which leads
 to two methods for the same endpoint but with a different `produces` list in the mapping annotation.
 
-One method which is called when json is requested and one when plain text is requested. Spring will
-take care of selecting the correct endpoint.
+One method when json gets requested and one when plain text gets requested. Spring will take care of
+selecting the correct endpoint.
 
 
 == multiple content types & default content type
@@ -116,7 +116,7 @@ public interface Api {
 }
 ----
 
-Both endpoints need to handle the success case (json or text) and the error (xml) case. So both
+Both endpoints need to handle the success case (json or text), and the error (xml) case. So both
 mappings contain the xml content type. To handle the multiple responses the return type is now
 `Object`.
 
@@ -155,5 +155,5 @@ public interface Api {
 }
 ----
 
-The response type is now wrapped by a `ResponseEntity` and to handle the multiple response type the
+The response wraps the type by a `ResponseEntity` and to handle the multiple response types the
 generic parameter is the *unknown* type.