The feature allows JSON files being used with @responseFile tags in the doc bloc to replace string content matching @responseFile:path/to/file.json in the content.
This reduces duplication and its more inlined with creating json drafts. Allowing more finer control of API documentation without hurting the overall documenting engine.
Here is what I am doing with this feature locally.
I am creating various json draft 7 versions and replacing the content where needed using replace tags
The main sample.json file
{
"$schema": "https://json-schema.org/draft-07/schema",
"$id": "Sample",
"description": "The Sample entity",
"title": "Sample Entity",
"type": "object",
"properties": {
"id": {
"description": "The id of the entity",
"type": "number"
},
"name": {
"description": "The entity name",
"type": "number"
},
"nested_sample": {
"description": "Null when not present else sample",
"type": [
null,
"@responseFile:responses/nested-sample/nested-sample.json"
]
},
"created_at": {
"description": "The date time when created",
"type": "string",
"format": "Rfc3339String",
"examples": [
"2019-03-03T00:00:00+00"
]
},
"updated_at": {
"description": "The Date time when updated",
"type": "string",
"format": "Rfc3339String",
"examples": [
"2019-03-03T00:00:00+00"
]
}
},
"required": [
"id",
"name",
"nested_sample",
"created_at",
"updated_at"
]
}
The nested-sample.json file
{
"$schema": "https://json-schema.org/draft-07/schema",
"$id": "SampleNested",
"description": "The Sample entity",
"title": "Sample Entity",
"type": "object",
"properties": {
"id": {
"description": "The id of the entity",
"type": "number"
},
"nestedValue": {
"description": "Nested Value description",
"type": [
"string",
"boolean",
"number"
]
},
"sampleId": {
"description": "Parent sample id",
"type": "number"
},
}
}
The final sample.json file
{
"$schema": "https://json-schema.org/draft-07/schema",
"$id": "Sample",
"description": "The Sample entity",
"title": "Sample Entity",
"type": "object",
"properties": {
"id": {
"description": "The id of the entity",
"type": "number"
},
"name": {
"description": "The entity name",
"type": "number"
},
"nested_sample": {
"description": "Null when not present else sample",
"type": [
null,
{
"$schema": "https://json-schema.org/draft-07/schema",
"$id": "SampleNested",
"description": "The Sample entity",
"title": "Sample Entity",
"type": "object",
"properties": {
"id": {
"description": "The id of the entity",
"type": "number"
},
"nestedValue": {
"description": "Nested Value description",
"type": [
"string",
"boolean",
"number"
]
},
"sampleId": {
"description": "Parent sample id",
"type": "number"
},
}
}
]
},
"created_at": {
"description": "The date time when created",
"type": "string",
"format": "Rfc3339String",
"examples": [
"2019-03-03T00:00:00+00"
]
},
"updated_at": {
"description": "The Date time when updated",
"type": "string",
"format": "Rfc3339String",
"examples": [
"2019-03-03T00:00:00+00"
]
}
},
"required": [
"id",
"name",
"nested_sample",
"created_at",
"updated_at"
]
}
The feature allows JSON files being used with @responseFile tags in the doc bloc to replace string content matching @responseFile:path/to/file.json in the content.
This reduces duplication and its more inlined with creating json drafts. Allowing more finer control of API documentation without hurting the overall documenting engine.
Here is what I am doing with this feature locally.
I am creating various json draft 7 versions and replacing the content where needed using replace tags
The main sample.json file
The nested-sample.json file
The final sample.json file