Skip to content

Commit 437d7da

Browse files
xeromankxeromank
authored
Feat : Schema reuse through subschema (#246)
* feat : Input a name for the subschema * feat : Input a name for the subschema * feat : Make sub schema * fix: lint * fix: requested & Suggested
1 parent 2900374 commit 437d7da

File tree

5 files changed

+194
-1
lines changed

5 files changed

+194
-1
lines changed

‎restdocs-api-spec-jsonschema/src/main/kotlin/com/epages/restdocs/apispec/jsonschema/JsonSchemaFromFieldDescriptorsGenerator.kt‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -168,11 +168,13 @@ class JsonSchemaFromFieldDescriptorsGenerator {
168168
.build()
169169
)
170170
} else {
171+
val schemaName = propertyField?.fieldDescriptor?.attributes?.schemaName
171172
builder.addPropertySchema(
172173
propertyName,
173174
traverse(
174175
traversedSegments, fields,
175176
ObjectSchema.builder()
177+
.title(schemaName)
176178
.description(propertyField?.fieldDescriptor?.description) as ObjectSchema.Builder
177179
)
178180
)

‎restdocs-api-spec-jsonschema/src/test/kotlin/com/epages/restdocs/apispec/jsonschema/JsonSchemaFromFieldDescriptorsGeneratorTest.kt‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,22 @@ class JsonSchemaFromFieldDescriptorsGeneratorTest {
4040

4141
private var schemaString: String? = null
4242

43+
@Test
44+
@Throws(IOException::class)
45+
fun should_generate_reuse_schema() {
46+
givenFieldDescriptorsWithSchemaName()
47+
48+
whenSchemaGenerated()
49+
50+
then(schema).isInstanceOf(ObjectSchema::class.java)
51+
val objectSchema = schema as ObjectSchema?
52+
val postSchema = objectSchema?.propertySchemas?.get("post") as ObjectSchema
53+
val shippingAddressSchema = postSchema.propertySchemas["shippingAddress"] as ObjectSchema
54+
then(shippingAddressSchema.title).isEqualTo("Address")
55+
val billingAddressSchema = postSchema.propertySchemas["billingAddress"] as ObjectSchema
56+
then(billingAddressSchema.title).isEqualTo("Address")
57+
}
58+
4359
@Test
4460
@Throws(IOException::class)
4561
fun should_generate_complex_schema() {
@@ -789,6 +805,23 @@ class JsonSchemaFromFieldDescriptorsGeneratorTest {
789805
)
790806
}
791807

808+
private fun givenFieldDescriptorsWithSchemaName() {
809+
810+
fieldDescriptors = listOf(
811+
FieldDescriptor(
812+
"post",
813+
"some",
814+
"OBJECT",
815+
),
816+
FieldDescriptor("post.shippingAddress", "some", "OBJECT", attributes = Attributes(schemaName = "Address")),
817+
FieldDescriptor("post.shippingAddress.firstName", "some", "STRING"),
818+
FieldDescriptor("post.shippingAddress.valid", "some", "BOOLEAN"),
819+
FieldDescriptor("post.billingAddress", "some", "OBJECT", attributes = Attributes(schemaName = "Address")),
820+
FieldDescriptor("post.billingAddress.firstName", "some", "STRING"),
821+
FieldDescriptor("post.billingAddress.valid", "some", "BOOLEAN"),
822+
)
823+
}
824+
792825
private fun thenSchemaValidatesJson(json: String) {
793826
schema!!.validate(if (json.startsWith("[")) JSONArray(json) else JSONObject(json))
794827
}

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

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -91,7 +91,8 @@ open class FieldDescriptor(
9191
data class Attributes(
9292
val validationConstraints: List<Constraint> = emptyList(),
9393
val enumValues: List<Any> = emptyList(),
94-
val itemsType: String? = null
94+
val itemsType: String? = null,
95+
val schemaName: String? = null,
9596
)
9697

9798
data class Constraint(

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

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ import com.epages.restdocs.apispec.model.SimpleType
1414
import com.epages.restdocs.apispec.model.groupByPath
1515
import com.epages.restdocs.apispec.openapi3.SecuritySchemeGenerator.addSecurityDefinitions
1616
import com.epages.restdocs.apispec.openapi3.SecuritySchemeGenerator.addSecurityItemFromSecurityRequirements
17+
import com.fasterxml.jackson.module.kotlin.jacksonObjectMapper
1718
import com.fasterxml.jackson.module.kotlin.readValue
1819
import io.swagger.v3.core.util.Json
1920
import io.swagger.v3.oas.models.Components
@@ -76,11 +77,41 @@ object OpenApi3Generator {
7677
resources,
7778
oauth2SecuritySchemeDefinition
7879
)
80+
7981
extractDefinitions()
82+
makeSubSchema()
8083
addSecurityDefinitions(oauth2SecuritySchemeDefinition)
8184
}
8285
}
8386

87+
private fun OpenAPI.makeSubSchema() {
88+
val schemas = this.components.schemas
89+
val subSchemas = mutableMapOf<String, Schema<Any>>()
90+
schemas.forEach {
91+
val schema = it.value
92+
if (schema.properties != null) {
93+
makeSubSchema(subSchemas, schema.properties)
94+
}
95+
}
96+
97+
if (subSchemas.isNotEmpty()) {
98+
this.components.schemas.putAll(subSchemas)
99+
}
100+
}
101+
102+
private fun makeSubSchema(schemas: MutableMap<String, Schema<Any>>, properties: Map<String, Schema<Any>>) {
103+
properties.asSequence().filter { it.value.title != null }.forEach {
104+
val objectMapper = jacksonObjectMapper()
105+
val subSchema = it.value
106+
val strSubSchema = objectMapper.writeValueAsString(subSchema)
107+
val copySchema = objectMapper.readValue(strSubSchema, subSchema.javaClass)
108+
val schemaTitle = copySchema.title
109+
subSchema.`$ref`("#/components/schemas/$schemaTitle")
110+
schemas[schemaTitle] = copySchema
111+
makeSubSchema(schemas, copySchema.properties)
112+
}
113+
}
114+
84115
fun generateAndSerialize(
85116
resources: List<ResourceModel>,
86117
servers: List<Server>,
@@ -132,6 +163,8 @@ object OpenApi3Generator {
132163
schemasToKeys.getValue(it) to it
133164
}.toMap()
134165
}
166+
167+
this.components
135168
}
136169

137170
private fun List<MediaType>.extractSchemas(
@@ -453,24 +486,28 @@ object OpenApi3Generator {
453486
.map { it as Boolean }
454487
.forEach { this.addEnumItem(it) }
455488
}
489+
456490
SimpleType.STRING.name.toLowerCase() -> StringSchema().apply {
457491
this._default(parameterDescriptor.defaultValue?.let { it as String })
458492
parameterDescriptor.attributes.enumValues
459493
.map { it as String }
460494
.forEach { this.addEnumItem(it) }
461495
}
496+
462497
SimpleType.NUMBER.name.toLowerCase() -> NumberSchema().apply {
463498
this._default(parameterDescriptor.defaultValue?.asBigDecimal())
464499
parameterDescriptor.attributes.enumValues
465500
.map { it.asBigDecimal() }
466501
.forEach { this.addEnumItem(it) }
467502
}
503+
468504
SimpleType.INTEGER.name.toLowerCase() -> IntegerSchema().apply {
469505
this._default(parameterDescriptor.defaultValue?.asInt())
470506
parameterDescriptor.attributes.enumValues
471507
.map { it.asInt() }
472508
.forEach { this.addEnumItem(it) }
473509
}
510+
474511
else -> throw IllegalArgumentException("Unknown type '${parameterDescriptor.type}'")
475512
}
476513
}

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

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,17 @@ class OpenApi3GeneratorTest {
3030
lateinit var openApiSpecJsonString: String
3131
lateinit var openApiJsonPathContext: DocumentContext
3232

33+
@Test
34+
fun `should convert multi level schema model to openapi`() {
35+
givenPutProductResourceModel()
36+
37+
whenOpenApiObjectGenerated()
38+
39+
val optionDTOPath = "components.schemas.OptionDTO"
40+
then(openApiJsonPathContext.read<LinkedHashMap<String, Any>>("$optionDTOPath.properties.name")).isNotNull()
41+
then(openApiJsonPathContext.read<LinkedHashMap<String, Any>>("$optionDTOPath.properties.id")).isNotNull()
42+
}
43+
3344
@Test
3445
fun `should convert single resource model to openapi`() {
3546
givenGetProductResourceModel()
@@ -929,6 +940,21 @@ class OpenApi3GeneratorTest {
929940
)
930941
}
931942

943+
private fun givenPutProductResourceModel() {
944+
resources = listOf(
945+
ResourceModel(
946+
operationId = "test",
947+
summary = "summary",
948+
description = "description",
949+
privateResource = false,
950+
deprecated = false,
951+
tags = setOf("tag1", "tag2"),
952+
request = getProductPutRequest(),
953+
response = getProductPutResponse(Schema("ProductPutResponse"))
954+
)
955+
)
956+
}
957+
932958
private fun givenGetProductResourceModel() {
933959
resources = listOf(
934960
ResourceModel(
@@ -1055,6 +1081,54 @@ class OpenApi3GeneratorTest {
10551081
)
10561082
}
10571083

1084+
private fun getProductPutResponse(schema: Schema? = null): ResponseModel {
1085+
return ResponseModel(
1086+
status = 200,
1087+
contentType = "application/json",
1088+
schema = schema,
1089+
headers = listOf(
1090+
HeaderDescriptor(
1091+
name = "SIGNATURE",
1092+
description = "This is some signature",
1093+
type = "STRING",
1094+
optional = false
1095+
)
1096+
),
1097+
responseFields = listOf(
1098+
FieldDescriptor(
1099+
path = "id",
1100+
description = "product id",
1101+
type = "STRING"
1102+
),
1103+
FieldDescriptor(
1104+
path = "option",
1105+
description = "option",
1106+
type = "OBJECT",
1107+
attributes = Attributes(schemaName = "OptionDTO")
1108+
),
1109+
FieldDescriptor(
1110+
path = "option.id",
1111+
description = "option id",
1112+
type = "STRING"
1113+
),
1114+
FieldDescriptor(
1115+
path = "option.name",
1116+
description = "option name",
1117+
type = "STRING"
1118+
),
1119+
),
1120+
example = """
1121+
{
1122+
"id": "pid12312",
1123+
"option": {
1124+
"id": "otid00001",
1125+
"name": "Option name"
1126+
}
1127+
}
1128+
""".trimIndent(),
1129+
)
1130+
}
1131+
10581132
private fun getProductHalResponse(schema: Schema? = null): ResponseModel {
10591133
return ResponseModel(
10601134
status = 200,
@@ -1152,6 +1226,52 @@ class OpenApi3GeneratorTest {
11521226
)
11531227
}
11541228

1229+
private fun getProductPutRequest(): RequestModel {
1230+
return RequestModel(
1231+
path = "/products/{id}",
1232+
method = HTTPMethod.PUT,
1233+
headers = listOf(),
1234+
pathParameters = listOf(),
1235+
queryParameters = listOf(),
1236+
formParameters = listOf(),
1237+
securityRequirements = null,
1238+
requestFields = listOf(
1239+
FieldDescriptor(
1240+
path = "id",
1241+
description = "product id",
1242+
type = "STRING"
1243+
),
1244+
FieldDescriptor(
1245+
path = "option",
1246+
description = "option",
1247+
type = "OBJECT",
1248+
attributes = Attributes(schemaName = "OptionDTO")
1249+
),
1250+
FieldDescriptor(
1251+
path = "option.id",
1252+
description = "option id",
1253+
type = "STRING"
1254+
),
1255+
FieldDescriptor(
1256+
path = "option.name",
1257+
description = "option name",
1258+
type = "STRING"
1259+
),
1260+
),
1261+
contentType = "application/json",
1262+
example = """
1263+
{
1264+
"id": "pid12312",
1265+
"option": {
1266+
"id": "otid00001",
1267+
"name": "Option name"
1268+
}
1269+
}
1270+
""".trimIndent(),
1271+
schema = Schema("ProductPutRequest")
1272+
)
1273+
}
1274+
11551275
private fun getProductRequestWithMultiplePathParameters(getSecurityRequirement: () -> SecurityRequirements = ::getOAuth2SecurityRequirement): RequestModel {
11561276
return RequestModel(
11571277
path = "/products/{id}-{subId}",

0 commit comments

Comments
 (0)