Ability to allow json files to replace @responseFile tags with files mapped

[maxgaurav]

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"
  ]
}

[maxgaurav]

Let me know you want to have a single squashed commit before further evaluation.