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)