improve grammar & text

Author: hauner

docs/modules/ROOT/pages/gradle.adoc

@@ -1,12 +1,9 @@
 = Gradle Plugin
 include::partial$links.adoc[]
 
-The xref:gradle::index.adoc[openapi-processor-gradle] is currently the only tool to run any of the
-**openapi-processor**'s.
+The xref:gradle::index.adoc[openapi-processor-gradle] gradle plugin can run any of the **openapi-processor**'s.
 
-To use it in a gradle project the gradle file of the project requires a few additional instructions.
-The following sections describe how to activate & configure **openapi-processor-spring** in a
-`build.gradle` file.
+To use it in a Gradle project, the Gradle file of the project requires a few additional instructions. The following sections describe how to activate & configure **openapi-processor-spring** in a `build.gradle` file.
 
 
 == adding the plugin
@@ -41,33 +38,24 @@ openapiProcessor {
 }
 ----
 
-* `processor`: (**required**) the processor dependency. This works in the same way as adding a
-dependency to a configuration in the gradle `dependencies` block. It is given here to avoid
-un-wanted side effects on the build dependencies of the project.
+* `processor`: (**required**) the processor dependency. This works in the same way as adding a dependency to a configuration in the gradle `dependencies` block. It is given here to avoid unwanted 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.
+* `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.
 
-* `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`
+* `targetDir`: (**required**) the output folder for generating interfaces and 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`
 directory.
 +
-See <<running processor-spring>> how to include the `targetDir` in compilation & packing.
+See <<running processor-spring>> how to include the `targetDir` in compilation and packing.
 
-* `mapping`: (**required**) provides the processor mapping options. This is a path
-to yaml file. See xref:processor/configuration.adoc[Configuration] for a description of the mapping
-yaml. This replaces the `typeMappings` option.
+* `mapping`: (**required**) provides the processor mapping options. This is a path to the YAML file. See xref:processor/configuration.adoc[Configuration] for a description of the mapping YAML. This replaces the `typeMappings` option.
 
-* `showWarnings`: (**optional**) `true` to show warnings from the open api parser or `false`
-(default) to show no warnings (this option has currently no effect).
+* `showWarnings`: (**optional**) `true` to show warnings from the open api parser or `false` (default) to show no warnings (this option has currently no effect).
 
-* `parser`: (**optional**), sets the openapi parser used to read the OpenAPI description. Available values are `SWAGGER` (default), `OPENAPI4J` or `INTERNAL`.
-** `SWAGGER`: link:{swagger-parser}[Swagger OpenAPI parser, window="_blank"], supports *OpenAPI 3.0.x*
-** `OPENAPI4J`: link:{openapi4j}[openapi4j OpenAPI parser, window="_blank"], supports *OpenAPI 3.0.x*. It provides better validation than `SWAGGER`, unfortunately it is no longer maintained.
+* `parser`: (**optional**), sets the openapi parser used to read the OpenAPI description. Available values are `SWAGGER`, `OPENAPI4J` or `INTERNAL` (default).
 ** `INTERNAL`: link:{openapi-parser}[internal OpenAPI parser, window="_blank"], supports *OpenAPI 3.0.x* & *OpenAPI 3.1.0*.
-*** the 3.0.x parser provides JSON schema validation.
-*** the 3.1.0 parser is *experimental* and has no validation at the moment.
+** `SWAGGER`: link:{swagger-parser}[Swagger OpenAPI parser, window="_blank"], supports *OpenAPI 3.0.x*
+** `OPENAPI4J`: link:{openapi4j}[openapi4j OpenAPI parser, window="_blank"], supports *OpenAPI 3.0.x*. It provides better validation than `SWAGGER`, unfortunately it is no longer maintained and is deprecated.
+*** the parser provides JSON schema validation.
 
 == running processor-spring
 
@@ -89,14 +77,12 @@ sourceSets {
 }
 ----
 
-* and the `compileJava` task gets a dependency on `processSpring`, so it runs before compilation
-(again, assuming a java project):
+* and the `compileJava` task gets a dependency on `processSpring`, so it runs before compilation (again, assuming a java project):
 +
 [source,groovy]
 ----
 // generate api before compiling
 compileJava.dependsOn ('processSpring')
 ----
 
-Adding automatic compilation in this way will also automatically include the generated files into the
-`jar` build artifact.
+Adding automatic compilation in this way will also automatically include the generated files into the `jar` build artifact.

docs/modules/ROOT/pages/index.adoc

@@ -14,46 +14,38 @@ link:{oaps-license}[image:{badge-license}[]]
 link:{oap-central}[image:{badge-central}[]]
 
 
-*openapi-processor-spring* is an link:{openapi}[OpenAPI] interface & dto java code generator
-for link:{springboot}[Spring Boot].
+*openapi-processor-spring* is an link:{openapi}[OpenAPI] interface & dto java code generator for link:{springboot}[Spring Boot].
 
-It supports an approach where you explicitly define and document your Service API (using OpenAPI)
-with the Interface to the outside and its usage in mind before you implement it. You do not derive
-the API later from the implementation and its implicit design. (of course, adapt as you go...)
+It supports an approach where you explicitly define and document your Service API (using OpenAPI)with the Interface to the outside and its usage in mind before you implement it. You do not derive the API later from the implementation and its implicit design. (of course, adapt as you go...)
 
 The advantages are:
 
-* you have a single place to maintain the api which makes it easier to create a consistent api
-and keep the overview.
-* it is easy to document in plain text. You can use markdown in the OpenAPI `description`
-properties.
+* you have a single place to maintain the api which makes it easier to create a consistent api and keep the overview.
+* it is easy to document in plain text. You can use Markdown in the OpenAPI `description` properties.
 
-The processor generates java interfaces based on the endpoint description of the API and simple POJO  classes or records for parameter or response schemas defined in the API. The processor adds all the required  spring & jackson annotations to the interface and all that is left to *you* is the implementation of the generated interfaces in any way you like.
+The processor generates java interfaces based on the endpoint description of the API and simple POJO  classes or records for parameter or response schemas defined in the API. The processor adds all the required  spring & jackson annotations to the interface, and all that is left to *you* is the implementation of the generated interfaces in any way you like.
 
-The interfaces will help to keep the implementation in sync with the API. If anything relevant
-changes  in the API the interface changes and the compiler will warn that the interface is not
-implemented correctly.
+The interfaces will help to keep the implementation in sync with the API. If anything relevant changes in the API, the interface changes and the compiler will warn that the interface is not implemented correctly.
 
-The target programming language is Java so the generated code is usable from most JVM languages.
+The target programming language is Java. Therefore, the generated code is usable from most JVM languages.
 
 See the xref:processor/index.adoc[processor intro] for a short example.
 
 == Playground
 
-openapi-processor has a link:{oap-playground}[playground, window="_blank"] application. You can try
-out some samples, or your own yaml and view the code that the processor generates.
+openapi-processor has a link:{oap-playground}[playground, window="_blank"] application. You can try out some samples or your own YAML and view the code that the processor generates.
 
 == Features
 
 - generates **only java interfaces and java dto classes** (get/set POJOs or records) for all defined endpoints and schemas to allow full control of the endpoint implementation. It does not generate any other file. See xref:processor/index.adoc[processor].
 
 - **powerful type mappings with generic support** to map schemas defined in the openapi.yaml to existing java types.
 +
-For example to map the openapi `array` type to a different java collections or to map paging parameters and results to th Spring types like `Page<>` & `Pageable`.
+For example, to map the openapi `array` type to a different java collection or to map paging parameters and results to th Spring types like `Page<>` & `Pageable`.
 +
 mappings can be defined globally, for a specific response, parameter or endpoint and or http method (of an endpoint). See xref:mapping/index.adoc[type mapping].
 
-- Annotation based **WebFlux support**. Actually there is *no* explicit WebFlux support, but the mapping allows defining a *single*, and a *multi* wrapper class. *single* wraps non-array like result types(e.g. `Mono<>`). *multi* replaces array like result types or parameters with the given multi mapping. For example, it will replace `List<String>` with `Flux<String>` if the multi mapping contains the fully qualified `Flux` type. +
+- Annotation-based **WebFlux support**. Actually, there is *no* explicit WebFlux support, but the mapping allows defining a *single*, and a *multi* wrapper class. *single* wraps non-array like result types(e.g. `Mono<>`). *multi* replaces array like result types or parameters with the given multi mapping. For example, it will replace `List<String>` with `Flux<String>` if the multi mapping contains the fully qualified `Flux` type. +
 //[.badge .badge-since]+since 1.0.0.M13+
 
 - generates **human-readable code**.
@@ -73,7 +65,7 @@ correct code for an endpoint. That way the processor can still be used for all t
 //[.badge .badge-since]+since 1.0.0.M11+
 
 - 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).
+documentation from the code when the code originates from the documentation (i.e., an openapi.yaml).
 
 - *maven & gradle support* The plugin docs show how to run a processor and how to add the generated sources to the build.
 
@@ -92,11 +84,9 @@ artifact name is:
 
 == Feedback
 
-In case some feature is missing, or the generated code is not 100% what you would expect create an
-link:{oaps-issues}[issue]. Preferably with a test case. Providing a test case will help
-significantly :-)
+In case some feature is missing, or the generated code is not 100% what you would expect, create an link:{oaps-issues}[issue]. Preferably with a test case. Providing a test case will help significantly. :-)
 
-A _perfect_ test case is a single folder with two sub folders containing the source files, and the expected output files:
+A _perfect_ test case is a single folder with two subfolders containing the source files and the expected output files:
 
  my-test-case
  +--- inputs.yaml

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

@@ -1,9 +1,7 @@
 = Basic (primitive) mappings
 include::partial$links.adoc[]
 
-The OpenAPI specification defines a couple of basic link:{openapi-spec-types}[data types]. The
-basic data types are built-in into the processor. That means it will map the basic types
-automatically to a corresponding java type. There is no explicit type mapping required.
+The OpenAPI specification defines a couple of basic link:{openapi-spec-types}[data types]. The basic data types are built-in into the processor. That means it will map the basic types automatically to a corresponding java type. There is no explicit type mapping required.
 
 The types with no default mapping can be mapped to a java type using the mapping configuration.
 

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

@@ -2,9 +2,7 @@
 include::partial$links.adoc[]
 include::partial$vars.adoc[]
 
-The global mapping variations are also available as explicit endpoint mappings. Instead of adding
-the mapping in the global sections `map/types`, `map/parameters` and `map/responses` they can
-be placed in the `map/paths` section as properties to an endpoint given by its path.
+The global mapping variations are also available as explicit endpoint mappings. Instead of adding the mapping in the global sections `map/types`, `map/parameters` and `map/responses` they can be placed in the `map/paths` section as properties to an endpoint given by its path.
 
 [source,yaml]
 ----
@@ -16,20 +14,20 @@ map:
     # a path
     /foo:
 
-      # path specific result wrapper
+      # path-specific result wrapper
       result: {target type}
 
-      # path specific single wrapper
+      # path-specific single wrapper
       single: {target type}
 
-      # path specific multi wrapper
+      # path-specific multi wrapper
       multi: {target type}
 
-      # list of path specific mappings
+      # list of path-specific mappings
       types:
         - from: {source type}  =>  {target type}
 
-      # list of path specific parameter mappings, mapped by parameter name
+      # list of path-specific parameter mappings, mapped by parameter name
       parameters:
         - name: {parameter name}  =>  {target type}
 
@@ -39,7 +37,7 @@ map:
         # 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
+      # list of path-specific content mappings, mapped by content type
       responses:
         - content: {content type}  =>  {target type}
 
@@ -48,30 +46,30 @@ map:
       # excluding an endpoint
       exclude: true
 
-      # path specific result wrapper
+      # path-specific result wrapper
       result: {target type}
 
-      # path specific single wrapper
+      # path-specific single wrapper
       single: {target type}
 
-      # path specific multi wrapper
+      # path-specific multi wrapper
       multi: {target type}
 
-      # list of path specific mappings
+      # list of path-specific mappings
       types:
         - from: {source type}  =>  {target type}
 
-      # list of path specific parameter mappings, mapped by parameter name
+      # list of path-specific parameter mappings, mapped by parameter name
       parameters:
         - name: {parameter name}  =>  {target type}
 
-        # add a (usually technical) parameter that is not described in the OpenAPI
+        # add a (usually technical) parameter 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
+      # list of path-specific content mappings, mapped by content type
       responses:
         - content: {content type}  =>  {target type}
 ----
@@ -81,7 +79,7 @@ have any effect on other endpoints.
 
 == Endpoint mappings by http method
 
-It is possible to add mappings that apply only to a specific http method. Motivation for this is limiting the mapping only to the place where it is needed. Http method mappings have priority over other mappings. In general, the most specific mapping is used.
+It is possible to add mappings that apply only to a specific http method. The motivation for this is limiting the mapping only to the place where it is necessary. Http method mappings have priority over other mappings. In general, the most specific mapping is used.
 
 Here are a few examples of possible http endpoint mappings:
 

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

@@ -43,7 +43,7 @@ map:
       - listB @ io.oap.FooC
 ----
 
-NOTE: openapi-processor will only recognize *strings* values of an extension. It will ignore any other type.
+NOTE: openapi-processor will only recognize *string* values of an extension. It will ignore any other type.
 
 The mapping allows two variations: