Merge remote-tracking branch 'upstream/master' into #34-Support-bean-validation

# Conflicts:
#	src/testInt/groovy/com/github/hauner/openapi/generatr/GeneratrEndToEndTest.groovy

Author: Bastian Wilhelm

docs/generatr/parameter-additional.md

@@ -0,0 +1,34 @@
+---
+layout: default
+title: Additional Parameters
+parent: The generatr
+nav_order: 11
+---
+
+# Additional Parameters
+
+Sometimes it may be useful to add an additional parameter to an endpoint that is an implementation detail.
+It should not be part of the public api. Think of the `HttpServletRequest` or a custom Spring
+ `HandlerMethodArgumentResolver`.
+ 
+Such an additional parameter can be described in the mappings as an endpoint parameter. Assuming there
+is an endpoint `/foo` defined in the OpenAPI interfaces it is possible to add extra parameters by using
+an `add <paramter name>` `as <java type>` entry.
+
+```yaml
+    map:
+      paths:
+        /foo:
+
+          parameters:
+            - add: request
+              as: javax.servlet.http.HttpServletRequest
+```
+
+will add the *additional* parameter to the generated interface method. 
+
+```java
+    @GetMapping(path = "/foo")
+    ResponseEntity<?> getFoo(@RequestParam(name = "bar") String bar, HttpServletRequest request);
+```
+

docs/howto/file_download.md

@@ -5,7 +5,7 @@ parent: HowTo's
 nav_order: 10
 ---
 
-Describing an endpoint to download file attachments.
+# Describing an endpoint to download files
 
 ```yaml
     /v1/attachments/{id}:

docs/howto/file_upload.md

@@ -5,7 +5,7 @@ parent: HowTo's
 nav_order: 15
 ---
 
-Describing and endpoint for uploading a singe file:
+# Describing and endpoint for uploading a singe file
 
 ```yaml
     /attachments:
@@ -30,7 +30,7 @@ Describing and endpoint for uploading a singe file:
                   format: int64
 ```
 
-Describing an endpoint for uploading multiple files:
+# Describing an endpoint for uploading multiple files
 
 ```yaml
     /attachments:

docs/index.md

@@ -65,8 +65,8 @@ See the [release notes][generatr-releases]{:target="_blank"}.
 - gradle support via [openapi-generatr-gradle][generatr-gradle] plugin (the plugin is currently the only option
  to run the generatr).
 
-- <span class="label label-yellow">planned</span> add additional parameters to an endpoint which are not defined in
-  the openapi description. For example to pass a `HttpServletRequest` to the endpoint implementation.
+- 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>
 
 - <span class="label label-yellow">planned</span> handle multiple responses by generating one endpoint method for
   each response content type.

docs/mapping/basic.md

@@ -8,7 +8,7 @@ nav_order: 1
 # Basic (primitive) Mappings
 
 The OpenAPI specification defines a couple of basic [data types][openapi-spec-types]{:target="_blank"}.
-The basic data types are built-in in the generatr. That means the generatr will map the basic types
+The basic data types are built-in into the generatr. That means the generatr will map the basic types
 automatically to a corresponding java type. There is no explicit type mapping required.
 
 ## OpenAPI to Java type mapping

src/main/groovy/com/github/hauner/openapi/spring/converter/ApiConverter.groovy

@@ -16,15 +16,20 @@
 
 package com.github.hauner.openapi.spring.converter
 
-import com.github.hauner.openapi.spring.converter.schema.ParameterSchemaInfo
+import com.github.hauner.openapi.spring.converter.mapping.AddParameterTypeMapping
+import com.github.hauner.openapi.spring.converter.mapping.Mapping
+import com.github.hauner.openapi.spring.converter.mapping.MappingSchema
+import com.github.hauner.openapi.spring.converter.mapping.TargetType
+import com.github.hauner.openapi.spring.converter.mapping.TypeMapping
 import com.github.hauner.openapi.spring.converter.schema.RefResolver
-import com.github.hauner.openapi.spring.converter.schema.ResponseSchemaInfo
 import com.github.hauner.openapi.spring.converter.schema.SchemaInfo
 import com.github.hauner.openapi.spring.model.Api
 import com.github.hauner.openapi.spring.model.DataTypes
 import com.github.hauner.openapi.spring.model.Endpoint
 import com.github.hauner.openapi.spring.model.RequestBody as ModelRequestBody
+import com.github.hauner.openapi.spring.model.datatypes.MappedDataType
 import com.github.hauner.openapi.spring.model.datatypes.ObjectDataType
+import com.github.hauner.openapi.spring.model.parameters.AdditionalParameter
 import com.github.hauner.openapi.spring.model.parameters.CookieParameter
 import com.github.hauner.openapi.spring.model.parameters.HeaderParameter
 import com.github.hauner.openapi.spring.model.parameters.MultipartParameter
@@ -56,6 +61,25 @@ class ApiConverter {
     private DataTypeConverter dataTypeConverter
     private ApiOptions options
 
+    class MappingSchemaEndpoint implements MappingSchema {
+        Endpoint endpoint
+
+        @Override
+        String getPath () {
+            endpoint.path
+        }
+
+        @Override
+        String getName () {
+            null
+        }
+
+        @Override
+        String getContentType () {
+            null
+        }
+    }
+
     ApiConverter(ApiOptions options) {
         this.options = options
 
@@ -91,7 +115,8 @@ class ApiConverter {
             operations.each { httpOperation ->
                 def itf = target.getInterface (getInterfaceName (httpOperation))
 
-                Endpoint ep = new Endpoint (path: path, method: httpOperation.httpMethod)
+                Endpoint ep = new Endpoint (path: path,
+                    method: (httpOperation as HttpMethodTrait).httpMethod)
 
                 try {
                     def resolver = new RefResolver (api.components)
@@ -103,7 +128,8 @@ class ApiConverter {
                     itf.endpoints.add (ep)
 
                 } catch (UnknownDataTypeException e) {
-                    log.error ("failed to parse endpoint {} {} because of: '{}'", ep.path, ep.method, e.message)
+                    log.error ("failed to parse endpoint {} {} because of: '{}'",
+                        ep.path, ep.method, e.message)
                 }
             }
         }
@@ -113,6 +139,11 @@ class ApiConverter {
         parameters.each { Parameter parameter ->
             ep.parameters.add (createParameter (ep.path, parameter, dataTypes, resolver))
         }
+
+        List<Mapping> addMappings = findAdditionalParameter (ep)
+        addMappings.each {
+            ep.parameters.add (createAdditionalParameter (ep.path, it as AddParameterTypeMapping, dataTypes, resolver))
+        }
     }
 
     private void collectRequestBody (RequestBody requestBody, Endpoint ep, DataTypes dataTypes, RefResolver resolver) {
@@ -161,8 +192,11 @@ class ApiConverter {
     }
 
     private ModelParameter createParameter (String path, Parameter parameter, DataTypes dataTypes, resolver) {
-        def info = new ParameterSchemaInfo (path, parameter.schema, parameter.name)
-        info.resolver = resolver
+        def info = new SchemaInfo (
+            path: path,
+            name: parameter.name,
+            schema: parameter.schema,
+            resolver: resolver)
 
         DataType dataType = dataTypeConverter.convert (info, dataTypes)
 
@@ -181,6 +215,19 @@ class ApiConverter {
         }
     }
 
+    private ModelParameter createAdditionalParameter (String path, AddParameterTypeMapping mapping, DataTypes dataTypes, RefResolver resolver) {
+        TypeMapping tm = mapping.childMappings.first ()
+        TargetType tt = tm.targetType
+
+        def addType = new MappedDataType (
+            type: tt.name,
+            pkg: tt.pkg,
+            genericTypes: tt.genericNames
+        )
+
+        new AdditionalParameter (name: mapping.parameterName, required: true, dataType: addType)
+    }
+
     private ModelRequestBody createRequestBody (String contentType, SchemaInfo info, boolean required, DataTypes dataTypes) {
         DataType dataType = dataTypeConverter.convert (info, dataTypes)
 
@@ -209,12 +256,12 @@ class ApiConverter {
             def mediaType = contentEntry.value
             def schema = mediaType.schema
 
-            def info = new ResponseSchemaInfo (
-                path,
-                contentType,
-                schema,
-                inlineName)
-            info.resolver = resolver
+            def info = new SchemaInfo (
+                path: path,
+                contentType: contentType,
+                name: inlineName,
+                schema: schema,
+                resolver: resolver)
 
             DataType dataType = dataTypeConverter.convert (info, dataTypes)
 
@@ -228,6 +275,17 @@ class ApiConverter {
         responses
     }
 
+    private List<Mapping> findAdditionalParameter (Endpoint ep) {
+        def addMappings = options.typeMappings.findAll {
+            it.matches (Mapping.Level.ENDPOINT, new MappingSchemaEndpoint (endpoint: ep))
+        }.collectMany {
+            it.childMappings
+        }.findAll {
+            it.matches (Mapping.Level.ADD, null as MappingSchema)
+        }
+        addMappings
+    }
+
     private String getInlineRequestBodyName (String path) {
         Identifier.toClass (path) + 'RequestBody'
     }

src/main/groovy/com/github/hauner/openapi/spring/converter/ApiOptions.groovy

@@ -1,5 +1,5 @@
 /*
- * Copyright 2019 the original authors
+ * Copyright 2019-2020 the original authors
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -16,7 +16,7 @@
 
 package com.github.hauner.openapi.spring.converter
 
-import com.github.hauner.openapi.spring.converter.mapping.TypeMappingX
+import com.github.hauner.openapi.spring.converter.mapping.Mapping
 
 /**
  * Options of the generatr.
@@ -50,13 +50,14 @@ class ApiOptions {
      * provide additional type mapping information to map OpenAPI types to java types. The list can
      * contain the following mappings:
      *
-     * {@link com.github.hauner.openapi.spring.converter.mapping.TypeMapping}: used to globally override
-     * the mapping of an OpenAPI schema to a specific java type.
+     * {@link com.github.hauner.openapi.spring.converter.mapping.TypeMapping}: used to globally
+     * override the mapping of an OpenAPI schema to a specific java type.
      *
-     * {@link com.github.hauner.openapi.spring.converter.mapping.EndpointTypeMapping}: used to override
-     * parameter, response type mappings or to add additional parameters on a single endpoint.
+     * {@link com.github.hauner.openapi.spring.converter.mapping.EndpointTypeMapping}: used to
+     * override parameter/response type mappings or to add additional parameters on a single
+     * endpoint.
      */
-    List<TypeMappingX> typeMappings
+    List<Mapping> typeMappings
 
     /**
      * provide enabling Bean Validation (JSR303) annotations. Default is false (disabled)