more documentation

Author: hauner

docs/_sass/overrides.scss

@@ -28,3 +28,11 @@
 
   border-left: 0.5em solid $yellow-000;
 }
+
+.deprecated {
+  margin-left: 1em;
+  margin-right: 1em;
+  padding: 0.8em;
+
+  border-left: 0.5em solid $red-000;
+}

docs/generatr/configuration.md

@@ -0,0 +1,48 @@
+---
+layout: default
+title: Configuration
+parent: The generatr
+nav_order: 4
+---
+
+# Configuration
+
+The configuration of the generatr is given in the `mapping.yaml`. It does contain some general options
+and the type mapping information.
+
+
+A mapping yaml looks like this  
+
+    options:
+      package-name: com.github.hauner.openapi
+      bean-validation: true 
+    
+    map:
+     # see link below
+
+
+## options:
+
+- `package-name`: (**required**) the root package name of the generated interfaces & models. The package
+ folder tree will be created inside the `targetDir` (see [using gradle][docs-gradle]). 
+ 
+  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"`  
+  - and the final package name of the generated models will be `"${package-name}.model"`  
+  {: .mb-5 }
+  
+- `bean-validation` (**optional**, `true` or `false`) enables generation of bean validation annotations.
+ Defaults to `false`. See [Bean Validation][bean-validation]{:target="_blank"}.
+
+## map:
+
+Using type mapping we can tell the generatr 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. 
+
+The type mapping is described in [java type mapping][docs-mapping].
+
+
+[docs-mapping]: /openapi-generatr-spring/mapping/
+[docs-gradle]:  /openapi-generatr-spring/gradle.html
+[bean-validation]: https://beanvalidation.org/

docs/gradle-obsolete.md

@@ -7,9 +7,9 @@ nav_order: 10
 # Using Gradle (obsolete)
 {: .no_toc }
 
-Note: this page is out-of-date describing the previous version of the gradle plugin. See the latest
+**Deprecated**: this page is out-of-date, describing the previous version of the gradle plugin. See the latest
 documentation [here][docs-gradle].
-{: .note .info .mb-6}
+{: .note .deprecated .mb-6}
 
 The [openapi-generatr-gradle][generatr-gradle] is currently the only way to run a **openapi-generatr.** 
 

docs/gradle.md

@@ -62,11 +62,8 @@ block name.
 
             spring {
                 apiPath = "$projectDir/src/api/openapi.yaml"
-                typeMappings = "$projectDir/openapi-mapping.yaml"
-    
                 targetDir = "$projectDir/build/openapi"
-                packageName = "com.github.hauner.openapi.sample"
-        
+                mapping = "$projectDir/openapi-mapping.yaml"
                 showWarnings = true
             }        
 
@@ -75,28 +72,42 @@ block name.
 - `apiPath`: (**required**) the path to the `openapi.yaml` file and the main input for the generatr. If
 set in the top level block it will be used for all configured generatrs.
 
-- `typeMappings`: (**optional**) defines the type mapping if required. This is either a path to yaml
- file or a yaml string (i.e. the content of the yaml file). See [java type mapping][docs-mapping] for a
- description of the mapping yaml.
-
 - `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 directory.
 
   See [running the generatr][docs-running] how to include the `targetDir` in compilation & packing.  
 
+- `mapping`: (**required**, since 1.0.0.M6) provides the generatr mapping options. This is a path
+ to yaml file. See [Configuration][docs-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.
+
+
+   **Deprecated** the following options are deprecated starting with '1.0.0.M6'
+   See [Configuration][docs-configuration].  
+   {: .note .deprecated .mb-6}
+
+- `typeMappings`: (**optional**) defines the type mapping if required. This is either a path to yaml
+ file or a yaml string (i.e. the content of the yaml file). See [java type mapping][docs-mapping] for a
+ description of the mapping yaml. 
+ 
+  starting with '1.0.0.M6' this is replaced by the `mapping` option.
+
 - `packageName`: (**required**) the root package name of the generated interfaces & models. The package folder
  tree will be created inside `targetDir`. 
 
   Interfaces and models will be generated into the `api` and `model` subpackages of `packageName`.
 
   - so the final package name of the generated interfaces will be `"${packageName}.api"`  
   - and the final package name of the generated models will be `"${packageName}.model"`  
-{: .mb-5 }
-
-- `showWarnings`: (**optional**) `true` to show warnings from the open api parser or `false` (default) to
- show no warnings.
+  {: .mb-5 }
 
+  starting with '1.0.0.M6' it is recommended to provide this in the mapping yaml. See
+  [Configuration][docs-configuration].
+  {: .mb-5 }
 
 # running generatr-spring
 
@@ -128,4 +139,5 @@ Adding automatic compilation in this way will also automatically include the gen
 
 [generatr-gradle]: https://github.com/hauner/openapi-generatr-gradle
 [docs-mapping]: /openapi-generatr-spring/mapping/
+[docs-configuration]: /openapi-generatr-spring/generatr/configuration.html
 [docs-running]: #running-generatr-spring

docs/index.md

@@ -67,6 +67,13 @@ See the [release notes][generatr-releases]{:target="_blank"}.
 
 - add additional parameters to an endpoint which are not defined in the OpenAPI description. For example to pass
  a `HttpServletRequest` to the endpoint implementation. <span class="label label-green">since 1.0.0.M6</span>
+
+- supports bean validations. The constraints of the openapi description are mapped to java bean validation
+ annotations. <span class="label label-green">since 1.0.0.M6</span>
+ 
+- allows to exclude endpoints from generation. This is useful if the generatr does not create the correct code for
+ an endpoint. That way the generatr can still be used for all the other endpoints.
+   <span class="label label-green">since 1.0.0.M6</span>
 
 - <span class="label label-yellow">planned</span> handle multiple responses by generating one endpoint method for
   each response content type.

docs/links.md

@@ -8,7 +8,7 @@ nav_order: 30
 
 - [OpenAPI][openapi]{:target="_blank"}. Homepage of the OpenAPI Initiative.
 - [OpenAPI specification][openapi-spec]{:target="_blank"}. Github repository of the OpenAPI specification.
-- [OpenAPI tools:][openapi-tools]{:target="_blank"}. List of OpenAPI tools.
+- [OpenAPI tools][openapi-tools]{:target="_blank"}. List of OpenAPI tools.
 - "the" [OpenAPI generator][openapi-generator]{:target="_blank"}. Generate clients, servers and documentation from OpenAPI 2.0/3.x documents.
 
 [openapi]: https://www.openapis.org/

docs/mapping/endpoint.md

@@ -37,6 +37,8 @@ be placed in the `map/paths` section as properties to an endpoint given by its p
 
         # another path
         /foo2:
+          # excluding an endpoint
+          exclude: true
 
           # list of path specific mappings
           types:
@@ -57,3 +59,21 @@ be placed in the `map/paths` section as properties to an endpoint given by its p
 
 The mappings defined as properties of an endpoint will be used only for this endpoint. They don't
 have any effect on other endpoints.
+
+## excluding endpoints
+
+(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.
+
+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
+implementing the `Excluded` interface.
+
+ ```yaml
+   map:
+     /foo:
+       # excluding an endpoint
+       exclude: true
+ ```

docs/mapping/structure.md

@@ -5,10 +5,11 @@ parent: Type Mapping
 nav_order: 5
 ---
 
-# mapping.yaml structure
+# type mapping structure
 
-A type mapping yaml has multiple sections to define the different kinds of type mappings. All sections
- are optional.
+The type mapping is part of the mapping yaml (see [Configuration][docs-configuration]) and configured under
+the `map` key. The `map` key contains multiple sections to define the different kinds of type mappings.
+ All sections are optional.
 
 ```yaml
     map:
@@ -50,3 +51,5 @@ A type mapping yaml has multiple sections to define the different kinds of type
               to: ..
 
 ```
+
+[docs-configuration]: /openapi-generatr-spring/generatr/configuration.html