From 90a3bc4886e28d483bd275cfb715de9fcb51aa43 Mon Sep 17 00:00:00 2001 From: Paul Carter Date: Sun, 6 Jan 2019 15:12:29 +1000 Subject: [PATCH] Add optional description attributes for Open API 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 --- README.md | 3 +++ .../com/epages/restdocs/apispec/gradle/OpenApi3Task.kt | 1 + .../com/epages/restdocs/apispec/gradle/OpenApiBaseTask.kt | 5 +++++ .../com/epages/restdocs/apispec/gradle/OpenApiExtension.kt | 1 + .../kotlin/com/epages/restdocs/apispec/gradle/OpenApiTask.kt | 1 + .../restdocs/apispec/gradle/RestdocsOpenApi3TaskTest.kt | 1 + .../restdocs/apispec/gradle/RestdocsOpenApiTaskTest.kt | 1 + .../restdocs/apispec/gradle/RestdocsOpenApiTaskTestBase.kt | 1 + .../epages/restdocs/apispec/openapi2/OpenApi20Generator.kt | 5 ++++- .../restdocs/apispec/openapi2/OpenApi20GeneratorTest.kt | 3 ++- .../epages/restdocs/apispec/openapi3/OpenApi3Generator.kt | 4 ++++ .../restdocs/apispec/openapi3/OpenApi3GeneratorTest.kt | 4 +++- 12 files changed, 27 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 646e7c5f..65a2012e 100644 --- a/README.md +++ b/README.md @@ -111,6 +111,7 @@ openapi { //6 host = 'localhost:8080' basePath = '/api' title = 'My API' + description = 'My API description' version = '1.0.0' format = 'json' } @@ -118,6 +119,7 @@ openapi { //6 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` diff --git a/restdocs-api-spec-gradle-plugin/src/main/kotlin/com/epages/restdocs/apispec/gradle/OpenApi3Task.kt b/restdocs-api-spec-gradle-plugin/src/main/kotlin/com/epages/restdocs/apispec/gradle/OpenApi3Task.kt index c009e209..83cd5ba6 100644 --- a/restdocs-api-spec-gradle-plugin/src/main/kotlin/com/epages/restdocs/apispec/gradle/OpenApi3Task.kt +++ b/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 diff --git a/restdocs-api-spec-gradle-plugin/src/main/kotlin/com/epages/restdocs/apispec/gradle/OpenApiBaseTask.kt b/restdocs-api-spec-gradle-plugin/src/main/kotlin/com/epages/restdocs/apispec/gradle/OpenApiBaseTask.kt index 35fe2d8a..d8607421 100644 --- a/restdocs-api-spec-gradle-plugin/src/main/kotlin/com/epages/restdocs/apispec/gradle/OpenApiBaseTask.kt +++ b/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 } } diff --git a/restdocs-api-spec-gradle-plugin/src/main/kotlin/com/epages/restdocs/apispec/gradle/OpenApiExtension.kt b/restdocs-api-spec-gradle-plugin/src/main/kotlin/com/epages/restdocs/apispec/gradle/OpenApiExtension.kt index a82bac24..ec3e741b 100644 --- a/restdocs-api-spec-gradle-plugin/src/main/kotlin/com/epages/restdocs/apispec/gradle/OpenApiExtension.kt +++ b/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" diff --git a/restdocs-api-spec-gradle-plugin/src/main/kotlin/com/epages/restdocs/apispec/gradle/OpenApiTask.kt b/restdocs-api-spec-gradle-plugin/src/main/kotlin/com/epages/restdocs/apispec/gradle/OpenApiTask.kt index 88dcd977..c97357d2 100644 --- a/restdocs-api-spec-gradle-plugin/src/main/kotlin/com/epages/restdocs/apispec/gradle/OpenApiTask.kt +++ b/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 diff --git a/restdocs-api-spec-gradle-plugin/src/test/kotlin/com/epages/restdocs/apispec/gradle/RestdocsOpenApi3TaskTest.kt b/restdocs-api-spec-gradle-plugin/src/test/kotlin/com/epages/restdocs/apispec/gradle/RestdocsOpenApi3TaskTest.kt index 4d39fc52..4dceb9b2 100644 --- a/restdocs-api-spec-gradle-plugin/src/test/kotlin/com/epages/restdocs/apispec/gradle/RestdocsOpenApi3TaskTest.kt +++ b/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 diff --git a/restdocs-api-spec-gradle-plugin/src/test/kotlin/com/epages/restdocs/apispec/gradle/RestdocsOpenApiTaskTest.kt b/restdocs-api-spec-gradle-plugin/src/test/kotlin/com/epages/restdocs/apispec/gradle/RestdocsOpenApiTaskTest.kt index fb26cbed..09c04c78 100644 --- a/restdocs-api-spec-gradle-plugin/src/test/kotlin/com/epages/restdocs/apispec/gradle/RestdocsOpenApiTaskTest.kt +++ b/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 diff --git a/restdocs-api-spec-gradle-plugin/src/test/kotlin/com/epages/restdocs/apispec/gradle/RestdocsOpenApiTaskTestBase.kt b/restdocs-api-spec-gradle-plugin/src/test/kotlin/com/epages/restdocs/apispec/gradle/RestdocsOpenApiTaskTestBase.kt index c5017d20..5f27c277 100644 --- a/restdocs-api-spec-gradle-plugin/src/test/kotlin/com/epages/restdocs/apispec/gradle/RestdocsOpenApiTaskTestBase.kt +++ b/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 = arrayOf("http") var title = "API documentation" + var description = "the description for the API" var version = "1.0.0" var format = "json" diff --git a/restdocs-api-spec-openapi-generator/src/main/kotlin/com/epages/restdocs/apispec/openapi2/OpenApi20Generator.kt b/restdocs-api-spec-openapi-generator/src/main/kotlin/com/epages/restdocs/apispec/openapi2/OpenApi20Generator.kt index 29ab3095..b8d32bbc 100644 --- a/restdocs-api-spec-openapi-generator/src/main/kotlin/com/epages/restdocs/apispec/openapi2/OpenApi20Generator.kt +++ b/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 = 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 = 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) } diff --git a/restdocs-api-spec-openapi-generator/src/test/kotlin/com/epages/restdocs/apispec/openapi2/OpenApi20GeneratorTest.kt b/restdocs-api-spec-openapi-generator/src/test/kotlin/com/epages/restdocs/apispec/openapi2/OpenApi20GeneratorTest.kt index 717bf1fa..3949810e 100644 --- a/restdocs-api-spec-openapi-generator/src/test/kotlin/com/epages/restdocs/apispec/openapi2/OpenApi20GeneratorTest.kt +++ b/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)) diff --git a/restdocs-api-spec-openapi3-generator/src/main/kotlin/com/epages/restdocs/apispec/openapi3/OpenApi3Generator.kt b/restdocs-api-spec-openapi3-generator/src/main/kotlin/com/epages/restdocs/apispec/openapi3/OpenApi3Generator.kt index 9cf8653f..c58a07a0 100644 --- a/restdocs-api-spec-openapi3-generator/src/main/kotlin/com/epages/restdocs/apispec/openapi3/OpenApi3Generator.kt +++ b/restdocs-api-spec-openapi3-generator/src/main/kotlin/com/epages/restdocs/apispec/openapi3/OpenApi3Generator.kt @@ -45,6 +45,7 @@ object OpenApi3Generator { resources: List, servers: List, title: String = "API", + description: String? = null, version: String = "1.0.0", oauth2SecuritySchemeDefinition: Oauth2Configuration? = null ): OpenAPI { @@ -53,6 +54,7 @@ object OpenApi3Generator { this.servers = servers info = Info().apply { this.title = title + this.description = description this.version = version } paths = generatePaths( @@ -68,6 +70,7 @@ object OpenApi3Generator { resources: List, servers: List, title: String = "API", + description: String? = null, version: String = "1.0.0", oauth2SecuritySchemeDefinition: Oauth2Configuration? = null, format: String @@ -77,6 +80,7 @@ object OpenApi3Generator { resources = resources, servers = servers, title = title, + description = description, version = version, oauth2SecuritySchemeDefinition = oauth2SecuritySchemeDefinition )) diff --git a/restdocs-api-spec-openapi3-generator/src/test/kotlin/com/epages/restdocs/apispec/openapi3/OpenApi3GeneratorTest.kt b/restdocs-api-spec-openapi3-generator/src/test/kotlin/com/epages/restdocs/apispec/openapi3/OpenApi3GeneratorTest.kt index 272baef9..8ea2b5c8 100644 --- a/restdocs-api-spec-openapi3-generator/src/test/kotlin/com/epages/restdocs/apispec/openapi3/OpenApi3GeneratorTest.kt +++ b/restdocs-api-spec-openapi3-generator/src/test/kotlin/com/epages/restdocs/apispec/openapi3/OpenApi3GeneratorTest.kt @@ -152,6 +152,7 @@ class OpenApi3GeneratorTest { private fun thenInfoFieldsPresent() { then(openApiJsonPathContext.read("info.title")).isEqualTo("API") + then(openApiJsonPathContext.read("info.description")).isEqualTo("API Description") then(openApiJsonPathContext.read("info.version")).isEqualTo("1.0.0") } @@ -174,7 +175,8 @@ class OpenApi3GeneratorTest { "http://example.com/authorize", arrayOf("clientCredentials", "authorizationCode") ), - format = "json" + format = "json", + description = "API Description" ) println(openApiSpecJsonString)