Skip to content

Commit fe18455

Browse files
jgazeauJordan GAZEAU
jgazeau
and
Jordan GAZEAU
authored
Add default value management for ParameterDescriptor and OA2/OA3 JSON Schemas (#188)
* add default value management for ParameterDescriptor * review modifications Co-authored-by: Jordan GAZEAU <jordan.gazeau@soprabanking.com>
1 parent a77c1cf commit fe18455

7 files changed

Lines changed: 252 additions & 22 deletions

File tree

‎restdocs-api-spec-model/src/main/kotlin/com/epages/restdocs/apispec/model/ResourceModel.kt‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,7 @@ interface AbstractParameterDescriptor {
6262
val name: String
6363
val description: String
6464
val type: String
65+
val default: Any?
6566
val optional: Boolean
6667
val attributes: Attributes
6768
}
@@ -70,6 +71,7 @@ data class HeaderDescriptor(
7071
override val name: String,
7172
override val description: String,
7273
override val type: String,
74+
override val default: Any? = null,
7375
override val optional: Boolean,
7476
val example: String? = null,
7577
override val attributes: Attributes = Attributes()
@@ -99,6 +101,7 @@ data class ParameterDescriptor(
99101
override val name: String,
100102
override val description: String,
101103
override val type: String,
104+
override val default: Any? = null,
102105
override val optional: Boolean,
103106
val ignored: Boolean,
104107
override val attributes: Attributes = Attributes()

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

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -417,6 +417,7 @@ object OpenApi20Generator {
417417
name = parameterDescriptor.name
418418
description = parameterDescriptor.description
419419
type = parameterDescriptor.type.toLowerCase()
420+
default = parameterDescriptor.default
420421
}
421422
}
422423

@@ -434,6 +435,7 @@ object OpenApi20Generator {
434435
description = parameterDescriptor.description
435436
required = parameterDescriptor.optional.not()
436437
type = parameterDescriptor.type.toLowerCase()
438+
default = parameterDescriptor.default
437439
}
438440
}
439441

@@ -443,6 +445,7 @@ object OpenApi20Generator {
443445
description = parameterDescriptor.description
444446
required = parameterDescriptor.optional.not()
445447
type = parameterDescriptor.type.toLowerCase()
448+
default = parameterDescriptor.default
446449
}
447450
}
448451

@@ -452,6 +455,7 @@ object OpenApi20Generator {
452455
description = headerDescriptor.description
453456
required = headerDescriptor.optional.not()
454457
type = headerDescriptor.type.toLowerCase()
458+
default = headerDescriptor.default
455459
}
456460
}
457461

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

Lines changed: 90 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -22,8 +22,8 @@ import io.swagger.models.Response
2222
import io.swagger.models.Swagger
2323
import io.swagger.models.auth.BasicAuthDefinition
2424
import io.swagger.models.auth.OAuth2Definition
25+
import io.swagger.models.parameters.AbstractSerializableParameter
2526
import io.swagger.models.parameters.BodyParameter
26-
import io.swagger.models.parameters.Parameter
2727
import io.swagger.models.parameters.PathParameter
2828
import io.swagger.models.properties.StringProperty
2929
import io.swagger.parser.Swagger20Parser
@@ -252,6 +252,16 @@ class OpenApi20GeneratorTest {
252252
thenValidateOpenApi(openapi)
253253
}
254254

255+
@Test
256+
fun `should include default values`() {
257+
val api = givenResourcesWithRequestParametersWithDefaultValues()
258+
259+
val openapi = whenOpenApiObjectGenerated(api)
260+
261+
thenGetProductWith200ResponseIsGeneratedWithDefaultValue(openapi, api)
262+
thenValidateOpenApi(openapi)
263+
}
264+
255265
private fun whenExtractOrFindSchema(schemaNameAndSchemaMap: MutableMap<Model, String>, ordersSchema: Model, shopsSchema: Model) {
256266
OpenApi20Generator.extractOrFindSchema(schemaNameAndSchemaMap, ordersSchema, OpenApi20Generator.generateSchemaName("/orders"))
257267
OpenApi20Generator.extractOrFindSchema(schemaNameAndSchemaMap, shopsSchema, OpenApi20Generator.generateSchemaName("/shops"))
@@ -356,7 +366,13 @@ class OpenApi20GeneratorTest {
356366
successfulGetResponse
357367
.examples.get(successfulGetProductModel.response.contentType)
358368
).isEqualTo(successfulGetProductModel.response.example)
359-
thenParametersForGetMatch(productPath.get.parameters, successfulGetProductModel.request)
369+
thenParametersForGetMatch(productPath.get.parameters as List<AbstractSerializableParameter<*>>, successfulGetProductModel.request)
370+
}
371+
372+
private fun thenGetProductWith200ResponseIsGeneratedWithDefaultValue(openapi: Swagger, api: List<ResourceModel>) {
373+
val successfulGetProductModel = api[0]
374+
val productPath = openapi.paths.getValue(successfulGetProductModel.request.path)
375+
thenParametersForGetMatchWithDefaultValue(productPath.get.parameters as List<AbstractSerializableParameter<*>>, successfulGetProductModel.request)
360376
}
361377

362378
private fun thenPostProductWith200ResponseIsGenerated(openapi: Swagger, api: List<ResourceModel>) {
@@ -371,7 +387,7 @@ class OpenApi20GeneratorTest {
371387
successfulPostResponse!!
372388
.examples.get(successfulPostProductModel.response.contentType)
373389
).isEqualTo(successfulPostProductModel.response.example)
374-
thenParametersForPostMatch(productPath.post.parameters, successfulPostProductModel.request)
390+
thenParametersForPostMatch(productPath.post.parameters as List<AbstractSerializableParameter<*>>, successfulPostProductModel.request)
375391

376392
thenRequestAndResponseSchemataAreReferenced(productPath, successfulPostResponse, openapi.definitions)
377393
}
@@ -392,14 +408,14 @@ class OpenApi20GeneratorTest {
392408
val productResourceModel = api[0]
393409
val productPath = openapi.paths.getValue(productResourceModel.request.path)
394410

395-
thenParameterMatches(productPath.post.parameters, "formData", productResourceModel.request.requestParameters[0])
411+
thenParameterMatches(productPath.post.parameters as List<AbstractSerializableParameter<*>>, "formData", productResourceModel.request.requestParameters[0])
396412
}
397413

398414
private fun thenPutRequestShouldHaveFormDataParameters(openapi: Swagger, api: List<ResourceModel>) {
399415
val productResourceModel = api[0]
400416
val productPath = openapi.paths.getValue(productResourceModel.request.path)
401417

402-
thenParameterMatches(productPath.put.parameters, "formData", productResourceModel.request.requestParameters[0])
418+
thenParameterMatches(productPath.put.parameters as List<AbstractSerializableParameter<*>>, "formData", productResourceModel.request.requestParameters[0])
403419
}
404420

405421
private fun thenGetProductWith400ResponseIsGenerated(openapi: Swagger, api: List<ResourceModel>) {
@@ -410,26 +426,36 @@ class OpenApi20GeneratorTest {
410426
productPath.get.responses.get(badGetProductModel.response.status.toString())!!
411427
.examples.get(badGetProductModel.response.contentType)
412428
).isEqualTo(badGetProductModel.response.example)
413-
thenParametersForGetMatch(productPath.get.parameters, badGetProductModel.request)
429+
thenParametersForGetMatch(productPath.get.parameters as List<AbstractSerializableParameter<*>>, badGetProductModel.request)
430+
}
431+
432+
private fun thenParametersForGetMatch(parameters: List<AbstractSerializableParameter<*>>, request: RequestModel) {
433+
thenParameterMatches(parameters, "path", request.pathParameters[0])
434+
thenParameterMatches(parameters, "query", request.requestParameters[0])
435+
thenParameterMatches(parameters, "header", request.headers[0])
414436
}
415437

416-
private fun thenParametersForGetMatch(parameters: List<Parameter>, request: RequestModel) {
438+
private fun thenParametersForGetMatchWithDefaultValue(parameters: List<AbstractSerializableParameter<*>>, request: RequestModel) {
417439
thenParameterMatches(parameters, "path", request.pathParameters[0])
418440
thenParameterMatches(parameters, "query", request.requestParameters[0])
441+
thenParameterMatches(parameters, "query", request.requestParameters[1])
442+
thenParameterMatches(parameters, "query", request.requestParameters[2])
443+
thenParameterMatches(parameters, "query", request.requestParameters[3])
419444
thenParameterMatches(parameters, "header", request.headers[0])
420445
}
421446

422-
private fun thenParametersForPostMatch(parameters: List<Parameter>, request: RequestModel) {
447+
private fun thenParametersForPostMatch(parameters: List<AbstractSerializableParameter<*>>, request: RequestModel) {
423448
thenParameterMatches(parameters, "header", request.headers[0])
424449
}
425450

426-
private fun thenParameterMatches(parameters: List<Parameter>, type: String, parameterDescriptor: AbstractParameterDescriptor) {
451+
private fun thenParameterMatches(parameters: List<AbstractSerializableParameter<*>>, type: String, parameterDescriptor: AbstractParameterDescriptor) {
427452
val parameter = findParameterByTypeAndName(parameters, type, parameterDescriptor.name)
428453
then(parameter).isNotNull
429454
then(parameter!!.description).isEqualTo(parameterDescriptor.description)
455+
then(parameter!!.default).isEqualTo(parameterDescriptor.default)
430456
}
431457

432-
private fun findParameterByTypeAndName(parameters: List<Parameter>, type: String, name: String): Parameter? {
458+
private fun findParameterByTypeAndName(parameters: List<AbstractSerializableParameter<*>>, type: String, name: String): AbstractSerializableParameter<*>? {
433459
return parameters.firstOrNull { it.`in` == type && it.name == name }
434460
}
435461

@@ -518,6 +544,21 @@ class OpenApi20GeneratorTest {
518544
)
519545
}
520546

547+
private fun givenResourcesWithRequestParametersWithDefaultValues(): List<ResourceModel> {
548+
return listOf(
549+
ResourceModel(
550+
operationId = "test",
551+
summary = "summary",
552+
description = "description",
553+
privateResource = false,
554+
deprecated = false,
555+
tags = setOf("tag1", "tag2"),
556+
request = getProductRequestWithRequestParametersWithDefaultValue(),
557+
response = getProduct200Response(getProductPayloadExample())
558+
)
559+
)
560+
}
561+
521562
private fun givenPostProductResourceModelWithoutFieldDescriptors(): List<ResourceModel> {
522563
return listOf(
523564
ResourceModel(
@@ -888,6 +929,45 @@ class OpenApi20GeneratorTest {
888929
)
889930
}
890931

932+
private fun getProductRequestWithRequestParametersWithDefaultValue(): RequestModel {
933+
return getProductRequest().copy(
934+
requestParameters = listOf(
935+
ParameterDescriptor(
936+
name = "booleanParameter",
937+
description = "a boolean parameter",
938+
type = "BOOLEAN",
939+
optional = true,
940+
ignored = false,
941+
default = true
942+
),
943+
ParameterDescriptor(
944+
name = "stringParameter",
945+
description = "a string parameter",
946+
type = "STRING",
947+
optional = true,
948+
ignored = false,
949+
default = "a default value"
950+
),
951+
ParameterDescriptor(
952+
name = "numberParameter",
953+
description = "a number parameter",
954+
type = "NUMBER",
955+
optional = true,
956+
ignored = false,
957+
default = 1.0
958+
),
959+
ParameterDescriptor(
960+
name = "integerParameter",
961+
description = "a integer parameter",
962+
type = "INTEGER",
963+
optional = true,
964+
ignored = false,
965+
default = 2L
966+
)
967+
)
968+
)
969+
}
970+
891971
private fun productRequest(schema: Schema? = null, path: String = "/products", method: HTTPMethod = HTTPMethod.POST): RequestModel {
892972
return RequestModel(
893973
path = path,

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

Lines changed: 13 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
package com.epages.restdocs.apispec.openapi3
22

33
import com.epages.restdocs.apispec.jsonschema.JsonSchemaFromFieldDescriptorsGenerator
4+
import com.epages.restdocs.apispec.model.AbstractParameterDescriptor
45
import com.epages.restdocs.apispec.model.FieldDescriptor
56
import com.epages.restdocs.apispec.model.HTTPMethod
67
import com.epages.restdocs.apispec.model.HeaderDescriptor
@@ -38,6 +39,7 @@ import io.swagger.v3.oas.models.responses.ApiResponse
3839
import io.swagger.v3.oas.models.responses.ApiResponses
3940
import io.swagger.v3.oas.models.servers.Server
4041
import io.swagger.v3.oas.models.tags.Tag
42+
import java.math.BigDecimal
4143

4244
object OpenApi3Generator {
4345

@@ -339,7 +341,7 @@ object OpenApi3Generator {
339341
.map {
340342
it.name to Header().apply {
341343
description(it.description)
342-
schema = simpleTypeToSchema(it.type)
344+
schema = simpleTypeToSchema(it)
343345
}
344346
}.toMap().nullIfEmpty()
345347
}
@@ -408,7 +410,7 @@ object OpenApi3Generator {
408410
return PathParameter().apply {
409411
name = parameterDescriptor.name
410412
description = parameterDescriptor.description
411-
schema = simpleTypeToSchema(parameterDescriptor.type)
413+
schema = simpleTypeToSchema(parameterDescriptor)
412414
}
413415
}
414416

@@ -425,7 +427,7 @@ object OpenApi3Generator {
425427
name = parameterDescriptor.name
426428
description = parameterDescriptor.description
427429
required = parameterDescriptor.optional.not()
428-
schema = simpleTypeToSchema(parameterDescriptor.type)
430+
schema = simpleTypeToSchema(parameterDescriptor)
429431
}
430432
}
431433

@@ -434,18 +436,18 @@ object OpenApi3Generator {
434436
name = headerDescriptor.name
435437
description = headerDescriptor.description
436438
required = headerDescriptor.optional.not()
437-
schema = simpleTypeToSchema(headerDescriptor.type)
439+
schema = simpleTypeToSchema(headerDescriptor)
438440
example = headerDescriptor.example
439441
}
440442
}
441443

442-
private fun simpleTypeToSchema(type: String): Schema<*>? {
443-
return when (type.toLowerCase()) {
444-
SimpleType.BOOLEAN.name.toLowerCase() -> BooleanSchema()
445-
SimpleType.STRING.name.toLowerCase() -> StringSchema()
446-
SimpleType.NUMBER.name.toLowerCase() -> NumberSchema()
447-
SimpleType.INTEGER.name.toLowerCase() -> IntegerSchema()
448-
else -> throw IllegalArgumentException("Unknown type '$type'")
444+
private fun simpleTypeToSchema(parameterDescriptor: AbstractParameterDescriptor): Schema<*>? {
445+
return when (parameterDescriptor.type.toLowerCase()) {
446+
SimpleType.BOOLEAN.name.toLowerCase() -> BooleanSchema().apply { this._default(parameterDescriptor.default?.let { it as Boolean }) }
447+
SimpleType.STRING.name.toLowerCase() -> StringSchema().apply { this._default(parameterDescriptor.default?.let { it as String }) }
448+
SimpleType.NUMBER.name.toLowerCase() -> NumberSchema().apply { this._default(parameterDescriptor.default?.let { it as BigDecimal }) }
449+
SimpleType.INTEGER.name.toLowerCase() -> IntegerSchema().apply { this._default(parameterDescriptor.default?.let { it as Int }) }
450+
else -> throw IllegalArgumentException("Unknown type '${parameterDescriptor.type}'")
449451
}
450452
}
451453

0 commit comments

Comments
 (0)