Add optional description attributes for Open API (#67)

Open API plugin will accept an optional description attribute to populate the description attribute in the Info Object of the generated specification

Implements issue #66

Author: pgcarter

README.md

@@ -111,13 +111,15 @@ openapi { //6
     host = 'localhost:8080'
     basePath = '/api'
     title = 'My API'
+    description = 'My API description'
     version = '1.0.0'
     format = 'json'
 }
 
 openapi3 {
 	server = 'https://localhost:8080'
 	title = 'My API'
+	description = 'My API description'
 	version = '0.1.0'
 	format = 'yaml'
 }
@@ -329,6 +331,7 @@ The `restdocs-api-spec-gradle-plugin` takes the following configuration options
 Name | Description | Default value
 ---- | ----------- | -------------
 title | The title of the application. Used for the `title` attribute in the [Info object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#info-object) | `API documentation`
+description | A description of the application. Used for the `description` attribute in the [Info object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#info-object) | empty
 version | The version of the api. Used for the `version` attribute in the [Info object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#info-object) | project version
 format | The format of the output OpenAPI file - supported values are `json` and `yaml` | `json`
 separatePublicApi | Should the plugin generate an additional OpenAPI specification file that does not contain the resources marked as private | `false`

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

@@ -22,6 +22,7 @@ open class OpenApi3Task : OpenApiBaseTask() {
             resources = resourceModels,
             servers = servers,
             title = title,
+            description = apiDescription,
             version = apiVersion,
             oauth2SecuritySchemeDefinition = oauth2SecuritySchemeDefinition,
             format = format

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

@@ -8,6 +8,10 @@ abstract class OpenApiBaseTask : ApiSpecTask() {
     @Optional
     lateinit var title: String
 
+    @Input
+    @Optional
+    var apiDescription: String? = null
+
     @Input
     @Optional
     lateinit var apiVersion: String
@@ -26,6 +30,7 @@ abstract class OpenApiBaseTask : ApiSpecTask() {
         format = extension.format
         oauth2SecuritySchemeDefinition = extension.oauth2SecuritySchemeDefinition
         title = extension.title
+        apiDescription = extension.description
         apiVersion = extension.version
     }
 }

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

@@ -16,6 +16,7 @@ abstract class OpenApiBaseExtension(project: Project) : ApiSpecExtension(project
 
     var title = "API documentation"
     var version = project.version as? String ?: "1.0.0"
+    var description: String? = null
 
     var format = "json"
 

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

@@ -31,6 +31,7 @@ open class OpenApiTask : OpenApiBaseTask() {
             host = host,
             schemes = schemes.toList(),
             title = title,
+            description = apiDescription,
             version = apiVersion,
             oauth2SecuritySchemeDefinition = oauth2SecuritySchemeDefinition,
             format = format

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

@@ -108,6 +108,7 @@ class RestdocsOpenApi3TaskTest : RestdocsOpenApiTaskTestBase() {
             openapi3 {
                 servers = [ { url = "http://some.api" } ]
                 title = '$title'
+                description = '$description'
                 version = '$version'
                 format = '$format'
                 separatePublicApi = $separatePublicApi

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

@@ -17,6 +17,7 @@ class RestdocsOpenApiTaskTest : RestdocsOpenApiTaskTestBase() {
                 basePath = '$basePath'
                 schemes = ${schemes.joinToString(",", "['", "']")}
                 title = '$title'
+                description = '$description'
                 version = '$version'
                 format = '$format'
                 separatePublicApi = $separatePublicApi

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

@@ -29,6 +29,7 @@ abstract class RestdocsOpenApiTaskTestBase {
     var schemes: Array<String> = arrayOf("http")
 
     var title = "API documentation"
+    var description = "the description for the API"
     var version = "1.0.0"
 
     var format = "json"

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

@@ -43,6 +43,7 @@ object OpenApi20Generator {
         host: String = "localhost",
         schemes: List<String> = listOf("http"),
         title: String = "API",
+        description: String? = null,
         version: String = "1.0.0",
         oauth2SecuritySchemeDefinition: Oauth2Configuration? = null
     ): Swagger {
@@ -53,6 +54,7 @@ object OpenApi20Generator {
             this.schemes(schemes.map { Scheme.forValue(it) })
             info = Info().apply {
                 this.title = title
+                this.description = description
                 this.version = version
             }
             paths = generatePaths(
@@ -75,11 +77,12 @@ object OpenApi20Generator {
         host: String = "localhost",
         schemes: List<String> = listOf("http"),
         title: String = "API",
+        description: String? = null,
         version: String = "1.0.0",
         oauth2SecuritySchemeDefinition: Oauth2Configuration? = null,
         format: String
     ): String {
-        val specification = generate(resources, basePath, host, schemes, title, version, oauth2SecuritySchemeDefinition)
+        val specification = generate(resources, basePath, host, schemes, title, description, version, oauth2SecuritySchemeDefinition)
         return ApiSpecificationWriter.serialize(format, specification)
     }
 

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

@@ -142,7 +142,8 @@ class OpenApi20GeneratorTest {
                 "http://example.com/token",
                 "http://example.com/authorize",
                 arrayOf("application", "accessCode")
-            )
+            ),
+        description = "API description"
         )
 
         println(ApiSpecificationWriter.serialize("yaml", openapi))