Aggregate parameters & descriptions from multiple snippets (closes #63) (#69)

Author: cnsgithub

restdocs-api-spec-openapi-generator/src/main/kotlin/com/epages/restdocs/apispec/openapi2/OpenApi20Generator.kt

@@ -276,14 +276,16 @@ object OpenApi20Generator {
                     extractPathParameters(
                         firstModelForPathAndMethod
                     ).plus(
-                        firstModelForPathAndMethod.request.requestParameters.map {
-                            requestParameterDescriptor2Parameter(
-                                it
-                            )
-                    }).plus(
-                        firstModelForPathAndMethod.request.headers.map {
-                            header2Parameter(it)
-                        }
+                        modelsWithSamePathAndMethod
+                                .flatMap { it.request.requestParameters }
+                                .distinctBy { it.name }
+                                .map { requestParameterDescriptor2Parameter(it)
+                                }).plus(
+                        modelsWithSamePathAndMethod
+                                .flatMap { it.request.headers }
+                                .distinctBy { it.name }
+                                .map { header2Parameter(it)
+                            }
                     ).plus(
                         listOfNotNull<Parameter>(
                             requestFieldDescriptor2Parameter(

restdocs-api-spec-openapi-generator/src/test/kotlin/com/epages/restdocs/apispec/openapi2/OpenApi20GeneratorTest.kt

@@ -151,6 +151,23 @@ class OpenApi20GeneratorTest {
         thenValidateOpenApi(openapi)
     }
 
+    @Test
+    fun `should aggregate requests with same path and method but different parameters`() {
+        val api = givenResourcesWithSamePathAndContentTypeAndDifferentParameters()
+
+        val openapi = whenOpenApiObjectGenerated(api)
+
+        val params = openapi.getPath("/products/{id}").get.parameters
+
+        then(params).anyMatch { it.name == "id" }
+        then(params).anyMatch { it.name == "locale" }
+        then(params).anyMatch { it.name == "color" && it.description == "Changes the color of the product" }
+        then(params).anyMatch { it.name == "Authorization" }
+        then(params).hasSize(4) // should not contain duplicated parameter descriptions
+
+        thenValidateOpenApi(openapi)
+    }
+
     private fun whenOpenApiObjectGenerated(api: List<ResourceModel>): Swagger {
         val openapi = OpenApi20Generator.generate(
             resources = api,
@@ -421,6 +438,51 @@ class OpenApi20GeneratorTest {
         )
     }
 
+    private fun givenResourcesWithSamePathAndContentTypeAndDifferentParameters(): List<ResourceModel> {
+        return listOf(
+                ResourceModel(
+                        operationId = "test",
+                        summary = "summary",
+                        description = "description",
+                        privateResource = false,
+                        deprecated = false,
+                        tags = setOf("tag1", "tag2"),
+                        request = getProductRequest(),
+                        response = getProduct200Response(getProductPayloadExample())
+                ),
+                ResourceModel(
+                        operationId = "test",
+                        summary = "summary",
+                        description = "description",
+                        privateResource = false,
+                        deprecated = false,
+                        tags = setOf("tag1", "tag2"),
+                        request = getProductRequest(),
+                        response = getProduct200Response(getProductPayloadExample())
+                ),
+                ResourceModel(
+                        operationId = "test-1",
+                        summary = "summary 1",
+                        description = "description 1",
+                        privateResource = false,
+                        deprecated = false,
+                        tags = setOf("tag1", "tag2"),
+                        request = getProductRequestWithDifferentParameter("color", "Changes the color of the product"),
+                        response = getProduct200Response(getProductPayloadExample())
+                ),
+                ResourceModel(
+                        operationId = "test-1",
+                        summary = "summary 1",
+                        description = "description 1",
+                        privateResource = false,
+                        deprecated = false,
+                        tags = setOf("tag1", "tag2"),
+                        request = getProductRequestWithDifferentParameter("color", "Modifies the color of the product"),
+                        response = getProduct200Response(getProductPayloadExample())
+                )
+        )
+    }
+
     private fun postProduct200Response(example: String): ResponseModel {
         return ResponseModel(
             status = 200,
@@ -553,6 +615,18 @@ class OpenApi20GeneratorTest {
         )
     }
 
+    private fun getProductRequestWithDifferentParameter(name: String, description: String): RequestModel {
+        return getProductRequest().copy(requestParameters = listOf(
+                ParameterDescriptor(
+                        name = name,
+                        description = description,
+                        type = "STRING",
+                        optional = true,
+                        ignored = false
+                )
+        ))
+    }
+
     private fun getProductRequestWithBasicSecurity(): RequestModel {
         return RequestModel(
             path = "/products",

restdocs-api-spec-openapi3-generator/src/main/kotlin/com/epages/restdocs/apispec/openapi3/OpenApi3Generator.kt

@@ -224,21 +224,23 @@ object OpenApi3Generator {
         val firstModelForPathAndMethod = modelsWithSamePathAndMethod.first()
         return Operation().apply {
             operationId = firstModelForPathAndMethod.operationId
-            summary = firstModelForPathAndMethod.summary
-            description = firstModelForPathAndMethod.description
+            summary = modelsWithSamePathAndMethod.map { it.summary }.find { !it.isNullOrBlank() }
+            description = modelsWithSamePathAndMethod.map { it.description }.find { !it.isNullOrBlank() }
             tags = modelsWithSamePathAndMethod.flatMap { it.tags }.distinct().nullIfEmpty()
             deprecated = if (modelsWithSamePathAndMethod.all { it.deprecated }) true else null
             parameters =
                     extractPathParameters(
                         firstModelForPathAndMethod
                     ).plus(
-                        firstModelForPathAndMethod.request.requestParameters.map {
-                            requestParameterDescriptor2Parameter(
-                                it
-                            )
+                        modelsWithSamePathAndMethod
+                                .flatMap { it.request.requestParameters }
+                                .distinctBy { it.name }
+                                .map { requestParameterDescriptor2Parameter(it)
                     }).plus(
-                        firstModelForPathAndMethod.request.headers.map {
-                            header2Parameter(it)
+                        modelsWithSamePathAndMethod
+                                .flatMap { it.request.headers }
+                                .distinctBy { it.name }
+                                .map { header2Parameter(it)
                         }
                     ).nullIfEmpty()
             requestBody = resourceModelsToRequestBody(

restdocs-api-spec-openapi3-generator/src/test/kotlin/com/epages/restdocs/apispec/openapi3/OpenApi3GeneratorTest.kt

@@ -119,6 +119,23 @@ class OpenApi3GeneratorTest {
         thenOpenApiSpecIsValid()
     }
 
+    @Test
+    fun `should aggregate requests with same path and method but different parameters`() {
+        givenResourcesWithSamePathAndContentTypeAndDifferentParameters()
+
+        whenOpenApiObjectGenerated()
+
+        val params = openApiJsonPathContext.read<List<Map<String, String>>>("paths./products/{id}.get.parameters.*")
+
+        then(params).anyMatch { it["name"] == "id" }
+        then(params).anyMatch { it["name"] == "locale" }
+        then(params).anyMatch { it["name"] == "color" && it["description"] == "Changes the color of the product" }
+        then(params).anyMatch { it["name"] == "Authorization" }
+        then(params).hasSize(4) // should not contain duplicated parameter descriptions
+
+        thenOpenApiSpecIsValid()
+    }
+
     fun thenGetProductByIdOperationIsValid() {
         val productGetByIdPath = "paths./products/{id}.get"
         then(openApiJsonPathContext.read<List<String>>("$productGetByIdPath.tags")).isNotNull()
@@ -243,6 +260,51 @@ class OpenApi3GeneratorTest {
         )
     }
 
+    private fun givenResourcesWithSamePathAndContentTypeAndDifferentParameters() {
+        resources = listOf(
+                ResourceModel(
+                        operationId = "test",
+                        summary = "summary",
+                        description = "description",
+                        privateResource = false,
+                        deprecated = false,
+                        tags = setOf("tag1", "tag2"),
+                        request = getProductRequest(),
+                        response = getProductResponse()
+                ),
+                ResourceModel(
+                        operationId = "test",
+                        summary = "summary",
+                        description = "description",
+                        privateResource = false,
+                        deprecated = false,
+                        tags = setOf("tag1", "tag2"),
+                        request = getProductRequest(),
+                        response = getProductResponse()
+                ),
+                ResourceModel(
+                        operationId = "test-1",
+                        summary = "summary 1",
+                        description = "description 1",
+                        privateResource = false,
+                        deprecated = false,
+                        tags = setOf("tag1", "tag2"),
+                        request = getProductRequestWithDifferentParameter("color", "Changes the color of the product"),
+                        response = getProductResponse()
+                ),
+                ResourceModel(
+                        operationId = "test-1",
+                        summary = "summary 1",
+                        description = "description 1",
+                        privateResource = false,
+                        deprecated = false,
+                        tags = setOf("tag1", "tag2"),
+                        request = getProductRequestWithDifferentParameter("color", "Modifies the color of the product"),
+                        response = getProductResponse()
+                )
+        )
+    }
+
     private fun givenResourcesWithSamePathAndDifferentMethods() {
         resources = listOf(
             ResourceModel(
@@ -509,6 +571,18 @@ class OpenApi3GeneratorTest {
         )
     }
 
+    private fun getProductRequestWithDifferentParameter(name: String, description: String): RequestModel {
+        return getProductRequest().copy(requestParameters = listOf(
+                ParameterDescriptor(
+                        name = name,
+                        description = description,
+                        type = "STRING",
+                        optional = true,
+                        ignored = false
+                )
+        ))
+    }
+
     private fun thenOpenApiSpecIsValid() {
         val messages = OpenAPIParser().readContents(openApiSpecJsonString, emptyList(), ParseOptions()).messages
         then(messages).describedAs("OpenAPI validation messages should be empty").isEmpty()