feat: add support for contact object (ePages-de#208)

* feat: add support for contact object

Closes ePages-de#88

* docs: add documentation on how to define contacts

Author: mpbalmeida

README.md

@@ -483,6 +483,10 @@ openapi3 {
     title = 'My API title'
     version = '1.0.1'
     format = 'yaml'
+    contact = {
+		name = 'John Doe'
+		email = '[email protected]'
+	}
     separatePublicApi = true
     outputFileNamePrefix = 'my-api-spec'
     oauth2SecuritySchemeDefinition = {

restdocs-api-spec-gradle-plugin/src/main/kotlin/com/epages/restdocs/apispec/gradle/OpenApi3Task.kt

@@ -2,6 +2,7 @@ package com.epages.restdocs.apispec.gradle
 
 import com.epages.restdocs.apispec.model.ResourceModel
 import com.epages.restdocs.apispec.openapi3.OpenApi3Generator
+import io.swagger.v3.oas.models.info.Contact
 import io.swagger.v3.oas.models.servers.Server
 import org.gradle.api.tasks.Input
 import org.gradle.api.tasks.Optional
@@ -12,9 +13,14 @@ open class OpenApi3Task : OpenApiBaseTask() {
     @Optional
     var servers: List<Server> = listOf()
 
+    @Input
+    @Optional
+    var contact: Contact? = null
+
     fun applyExtension(extension: OpenApi3Extension) {
         super.applyExtension(extension)
         servers = extension.servers
+        contact = extension.contact
     }
 
     override fun generateSpecification(resourceModels: List<ResourceModel>): String {
@@ -26,7 +32,8 @@ open class OpenApi3Task : OpenApiBaseTask() {
             tagDescriptions = tagDescriptions,
             version = apiVersion,
             oauth2SecuritySchemeDefinition = oauth2SecuritySchemeDefinition,
-            format = format
+            format = format,
+            contact = contact
         )
     }
 }

restdocs-api-spec-gradle-plugin/src/main/kotlin/com/epages/restdocs/apispec/gradle/OpenApiExtension.kt

@@ -5,6 +5,7 @@ import com.fasterxml.jackson.databind.ObjectMapper
 import com.fasterxml.jackson.dataformat.yaml.YAMLFactory
 import com.fasterxml.jackson.module.kotlin.readValue
 import groovy.lang.Closure
+import io.swagger.v3.oas.models.info.Contact
 import io.swagger.v3.oas.models.servers.Server
 import org.gradle.api.Project
 import java.io.File
@@ -63,6 +64,7 @@ open class OpenApi3Extension(project: Project) : OpenApiBaseExtension(project) {
     override var outputFileNamePrefix = "openapi3"
 
     private var _servers: List<Server> = mutableListOf(Server().apply { url = "http://localhost" })
+    private var _contact: Contact? = null
 
     val servers
         get() = _servers
@@ -79,6 +81,13 @@ open class OpenApi3Extension(project: Project) : OpenApiBaseExtension(project) {
         _servers = serversActions.map { project.configure(Server(), it) as Server }
     }
 
+    val contact
+        get() = _contact
+
+    fun setContact(contact: Closure<Contact>) {
+        _contact = project.configure(Contact(), contact) as Contact
+    }
+
     companion object {
         const val name = "openapi3"
     }

restdocs-api-spec-gradle-plugin/src/test/kotlin/com/epages/restdocs/apispec/gradle/RestdocsOpenApi3TaskTest.kt

@@ -37,6 +37,18 @@ class RestdocsOpenApi3TaskTest : RestdocsOpenApiTaskTestBase() {
         thenSingleServerContainedInOutput()
     }
 
+    @Test
+    fun `should run openapi task with contact`() {
+        givenBuildFileWithOpenApiClosureWithContact()
+        givenResourceSnippet()
+
+        whenPluginExecuted()
+
+        thenApiSpecTaskSuccessful()
+        thenOutputFileFound()
+        thenContactContainedInOutput()
+    }
+
     @Test
     fun `should run openapi task with single server string`() {
         givenBuildFileWithOpenApiClosureWithSingleServerString()
@@ -67,6 +79,12 @@ class RestdocsOpenApi3TaskTest : RestdocsOpenApiTaskTestBase() {
         }
     }
 
+    private fun thenContactContainedInOutput() {
+        with(outputFileContext()) {
+            then(read<String>("info.contact.name")).isEqualTo("Test Contact")
+        }
+    }
+
     private fun thenHeaderWithDefaultValuesContainedInOutput() {
         with(outputFileContext()) {
             then(read<String>("paths./products/{id}.get.parameters[1].name")).isEqualTo("one")
@@ -86,6 +104,10 @@ class RestdocsOpenApi3TaskTest : RestdocsOpenApiTaskTestBase() {
         givenBuildFileWithOpenApiClosure("server", """{ url = 'http://some.api' }""")
     }
 
+    fun givenBuildFileWithOpenApiClosureWithContact() {
+        givenBuildFileWithOpenApiClosure("contact", """{ name = 'Test Contact' }""")
+    }
+
     override fun givenBuildFileWithOpenApiClosure() {
         givenBuildFileWithOpenApiClosure(
             "servers",
@@ -136,6 +158,7 @@ class RestdocsOpenApi3TaskTest : RestdocsOpenApiTaskTestBase() {
             baseBuildFile() + """
             openapi3 {
                 servers = [ { url = "http://some.api" } ]
+                contact = { name = "Test Contact" }
                 title = '$title'
                 description = '$description'
                 tagDescriptionsPropertiesFile = "tagDescriptions.yaml"

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

@@ -23,6 +23,7 @@ import io.swagger.v3.oas.models.PathItem
 import io.swagger.v3.oas.models.Paths
 import io.swagger.v3.oas.models.examples.Example
 import io.swagger.v3.oas.models.headers.Header
+import io.swagger.v3.oas.models.info.Contact
 import io.swagger.v3.oas.models.info.Info
 import io.swagger.v3.oas.models.media.BooleanSchema
 import io.swagger.v3.oas.models.media.Content
@@ -51,7 +52,8 @@ object OpenApi3Generator {
         description: String? = null,
         tagDescriptions: Map<String, String> = emptyMap(),
         version: String = "1.0.0",
-        oauth2SecuritySchemeDefinition: Oauth2Configuration? = null
+        oauth2SecuritySchemeDefinition: Oauth2Configuration? = null,
+        contact: Contact? = null
     ): OpenAPI {
         return OpenAPI().apply {
 
@@ -60,6 +62,7 @@ object OpenApi3Generator {
                 this.title = title
                 this.description = description
                 this.version = version
+                this.contact = contact
             }
             this.tags(
                 tagDescriptions.map {
@@ -86,7 +89,8 @@ object OpenApi3Generator {
         tagDescriptions: Map<String, String> = emptyMap(),
         version: String = "1.0.0",
         oauth2SecuritySchemeDefinition: Oauth2Configuration? = null,
-        format: String
+        format: String,
+        contact: Contact? = null
     ) =
         ApiSpecificationWriter.serialize(
             format,
@@ -97,7 +101,8 @@ object OpenApi3Generator {
                 description = description,
                 tagDescriptions = tagDescriptions,
                 version = version,
-                oauth2SecuritySchemeDefinition = oauth2SecuritySchemeDefinition
+                oauth2SecuritySchemeDefinition = oauth2SecuritySchemeDefinition,
+                contact = contact
             )
         )
 

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

@@ -18,6 +18,7 @@ import com.jayway.jsonpath.JsonPath
 import com.jayway.jsonpath.Option
 import io.swagger.parser.OpenAPIParser
 import io.swagger.parser.models.ParseOptions
+import io.swagger.v3.oas.models.info.Contact
 import io.swagger.v3.oas.models.servers.Server
 import org.assertj.core.api.BDDAssertions.then
 import org.junit.jupiter.api.Test
@@ -518,6 +519,7 @@ class OpenApi3GeneratorTest {
         then(openApiJsonPathContext.read<String>("info.title")).isEqualTo("API")
         then(openApiJsonPathContext.read<String>("info.description")).isEqualTo("API Description")
         then(openApiJsonPathContext.read<String>("info.version")).isEqualTo("1.0.0")
+        then(openApiJsonPathContext.read<String>("info.contact.name")).isEqualTo("Test Contact")
     }
 
     private fun thenTagFieldsPresent() {
@@ -578,7 +580,8 @@ class OpenApi3GeneratorTest {
             ),
             format = "json",
             description = "API Description",
-            tagDescriptions = mapOf("tag1" to "tag1 description", "tag2" to "tag2 description")
+            tagDescriptions = mapOf("tag1" to "tag1 description", "tag2" to "tag2 description"),
+            contact = Contact().apply { name = "Test Contact" }
         )
 
         println(openApiSpecJsonString)