Merge branch 'master' into groovy-3

Author: hauner

.gitignore

@@ -1,2 +1,3 @@
 out
 build
+.gradle

README.md

@@ -36,7 +36,7 @@ The structure looks like this:
                                      AnotherModelClass.java
                                      .. more model files ..
 
-The `mapping.yaml` contains the type mapping information and is an optional file.
+The `mapping.yaml` contains the type mapping information.
 
 See the [existing integration tests][generatr-int-resources] for a couple of examples. 
 

build.gradle

@@ -3,12 +3,14 @@ plugins {
     id 'java-library'
     id 'maven-publish'
     id 'com.jfrog.bintray' version '1.8.4'
+    id 'org.jetbrains.kotlin.jvm' version '1.3.61'
+    id 'org.jetbrains.dokka' version '0.10.0'
     id 'org.unbroken-dome.test-sets' version '2.2.1'
     id "com.github.ben-manes.versions" version "0.27.0"
 }
 
 group 'com.github.hauner.openapi'
-version '1.0.0.M5'
+version '1.0.0.M8'
 
 sourceCompatibility = JavaVersion.VERSION_1_8
 targetCompatibility = JavaVersion.VERSION_1_8
@@ -23,6 +25,7 @@ ext {
 
 repositories {
     mavenCentral()
+    jcenter()
     maven {
         url "https://oss.sonatype.org/content/repositories/snapshots"
     }
@@ -43,6 +46,7 @@ check.dependsOn testInt
 
 dependencies {
     implementation 'org.codehaus.groovy:groovy:3.0.0'
+    implementation 'org.jetbrains.kotlin:kotlin-stdlib'
     implementation 'io.swagger.parser.v3:swagger-parser:2.0.17'
     implementation 'com.google.googlejavaformat:google-java-format:1.7'
     compileOnly "com.github.hauner.openapi:openapi-generatr-api:$generatrApiVersion"
@@ -56,23 +60,33 @@ dependencies {
 
     testIntImplementation "com.github.hauner.openapi:openapi-generatr-api:$generatrApiVersion"
     testIntImplementation 'io.github.java-diff-utils:java-diff-utils:4.5'
+    testIntRuntimeOnly 'org.slf4j:slf4j-simple:1.7.30'
+//    testIntRuntimeOnly 'org.slf4j:slf4j-nop:1.6.1'
 }
 
 task sourcesJar(type: Jar, dependsOn: classes) {
-    archiveClassifier = 'sources'
+    archiveClassifier.set ('sources')
     from sourceSets.main.allSource
 }
 
-task javadocJar(type: Jar, dependsOn: groovydoc) {
-    archiveClassifier = 'javadoc'
-    from groovydoc.destinationDir
+task javadocJar(type: Jar, dependsOn: [groovydoc, dokka]) {
+    archiveClassifier.set ('javadoc')
+    from "$buildDir/docs"
 }
 
 artifacts {
     archives sourcesJar
     archives javadocJar
 }
 
+groovydoc {
+    destinationDir file("$buildDir/docs/groovy")
+}
+
+dokka {
+    outputFormat = 'html'
+    outputDirectory = "$buildDir/docs/kotlin"
+}
 
 bintray {
     user = bintrayUser

docs/Gemfile.lock

@@ -26,12 +26,12 @@ GEM
       ffi (>= 1.3.0)
     eventmachine (1.2.7)
     execjs (2.7.0)
-    faraday (0.17.1)
+    faraday (1.0.0)
       multipart-post (>= 1.2, < 3)
-    ffi (1.11.3)
+    ffi (1.12.2)
     forwardable-extended (2.6.0)
     gemoji (3.0.1)
-    github-pages (203)
+    github-pages (204)
       github-pages-health-check (= 1.16.1)
       jekyll (= 3.8.5)
       jekyll-avatar (= 0.7.0)
@@ -40,7 +40,7 @@ GEM
       jekyll-default-layout (= 0.1.4)
       jekyll-feed (= 0.13.0)
       jekyll-gist (= 1.5.0)
-      jekyll-github-metadata (= 2.12.1)
+      jekyll-github-metadata (= 2.13.0)
       jekyll-mentions (= 1.5.1)
       jekyll-optional-front-matter (= 0.3.2)
       jekyll-paginate (= 1.1.0)
@@ -117,8 +117,8 @@ GEM
       jekyll (>= 3.7, < 5.0)
     jekyll-gist (1.5.0)
       octokit (~> 4.2)
-    jekyll-github-metadata (2.12.1)
-      jekyll (~> 3.4)
+    jekyll-github-metadata (2.13.0)
+      jekyll (>= 3.4, < 5.0)
       octokit (~> 4.0, != 4.4.0)
     jekyll-mentions (1.5.1)
       html-pipeline (~> 2.3)
@@ -202,11 +202,12 @@ GEM
       jekyll (>= 3.5, < 5.0)
       jekyll-feed (~> 0.9)
       jekyll-seo-tag (~> 2.1)
-    minitest (5.13.0)
+    minitest (5.14.0)
     multipart-post (2.1.1)
     nokogiri (1.10.7)
       mini_portile2 (~> 2.4.0)
-    octokit (4.14.0)
+    octokit (4.15.0)
+      faraday (>= 0.9)
       sawyer (~> 0.8.0, >= 0.5.3)
     pathutil (0.16.2)
       forwardable-extended (~> 2.6)
@@ -217,7 +218,7 @@ GEM
     rouge (3.13.0)
     ruby-enum (0.7.2)
       i18n
-    rubyzip (2.0.0)
+    rubyzip (2.2.0)
     safe_yaml (1.0.5)
     sass (3.7.4)
       sass-listen (~> 4.0.0)
@@ -234,7 +235,7 @@ GEM
       ethon (>= 0.9.0)
     tzinfo (1.2.6)
       thread_safe (~> 0.1)
-    unicode-display_width (1.6.0)
+    unicode-display_width (1.6.1)
     zeitwerk (2.2.2)
 
 PLATFORMS

docs/_config.yml

@@ -15,6 +15,7 @@ exclude:
   - README.md
   - SCRATCH.md
   - api.md
+  - gradle-obsolete.md
 
 ##
 ## "just-the-docs" theme options

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/generatr/endpoints.md

@@ -0,0 +1,100 @@
+---
+layout: default
+title: Endpoints
+parent: The generatr
+nav_order: 6
+---
+
+# Endpoints
+
+A simple path of the OpenAPI description will usually produce a single endpoint method in the target
+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
+plain text:
+
+```yaml
+openapi: 3.0.2
+info:
+  title: test multiple response content types
+  version: 1.0.0
+
+paths:
+  /foo:
+    get:
+      responses:
+        '200':
+          description: json or plain text result
+          content:
+            application/json:
+                schema:
+                  $ref: '#/components/schemas/Foo'
+            text/plain:
+                schema:
+                  type: string
+        default:
+          description: error
+          content:
+            application/xml:
+                schema:
+                  $ref: '#/components/schemas/Error'
+
+components:
+
+  schemas:
+    Foo:
+      type: object
+      properties:
+        bar:
+          type: string
+
+    Error:
+      type: object
+      properties:
+        error:
+          type: string
+```
+
+A client request uses the request `Accept` header to tell the api which result content types it can
+handle. 
+
+Using a single endpoint method it has to decide which response to create. This leads to some boring
+`if/else` code. To avoid this the generatr creates one endpoint method for each possible response.
+
+For the example above it creates the following interface:
+
+```java
+package generated.api;
+
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.GetMapping;
+
+public interface Api {
+
+    @GetMapping(
+            path = "/foo",
+            produces = {"application/json", "application/xml"})
+    ResponseEntity<?> getFooApplicationJson();
+
+    @GetMapping(
+            path = "/foo",
+            produces = {"text/plain", "application/xml"})
+    ResponseEntity<?> getFooTextPlain();
+
+}
+```
+
+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.
+
+In the (contrived) example our api does also define another content type for all other result status
+codes: xml.
+
+Both endpoints need to handle the success case (json or text) and the error (xml) case. So both
+mappings contain the xml content type. With the different responses the `ResponseEntity` return type
+is now the *unknown* type. Successful response and error properties are different which prevents an
+explicit type as the result type.     

docs/generatr/models.md

@@ -2,7 +2,7 @@
 layout: default
 title: Models
 parent: The generatr
-nav_order: 6
+nav_order: 7
 ---
 
 # Models

docs/generatr/responses.md

@@ -5,10 +5,39 @@ parent: The generatr
 nav_order: 20
 ---
 
-## Responses
+# Responses
 
 All generated endpoints have a [`ResponseEntity<>`][spring-responseentity] result. This allows an endpoint
 implementation full control of the response at the cost of having to provide a `ResponseEntity` even if
 it could just return its pojo result.
 
+Here are a few examples:
+
+    public ResponseEntity<String> getFoo() {
+        return ResponseEntity.ok("foo");
+    }
+
+    public ResponseEntity<Long> getBar() {
+        return ResponseEntity.ok(5L);
+    }
+
+    public ResponseEntity<ResourceObject> getResourceObject() {
+        return ResponseEntity.ok(resourceObject);
+    }
+
+
+Depending on the number of defined response content types the parameter of the `ResponseEntity<>` will
+be either the java type or the *unknown type*.
+
+
+| # responses   | ResponseEntity<>                     |
+|:-------------:|:------------------------------------:| 
+| one           | `ResponseEntity<java type>`          | 
+| multiple      | `ResponseEntity<?>`                  | 
+
+
+
+
+
+
 [spring-responseentity]: https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/http/ResponseEntity.html