Nested schemas do not show description in swagger-ui

When working with swagger-ui, I’ve found that nested schemas do not show the description. While I found the issue in swagger ui, I believe the actual fix is in swagger-js. I was able to track this down in swagger-ui.js to the resolveSchema helper function.

This function is called within the processModel function (which is within the schemaToHTML function in swagger-client.js). The problem occurs at line 2432 in swagger-client.js:

// Resolve the schema (Handle nested schemas)
cProperty = helpers.resolveSchema(cProperty);

I temporarily put in a couple of console.log statements to print the before and after values of cProperty:

console.log("Property Before: ", cProperty);

// Resolve the schema (Handle nested schemas)
cProperty = helpers.resolveSchema(cProperty);

console.log("Property After: ", cProperty);

The first console.log gives the following:

description: "Some description here"
schema: Object
  $ref: "#/definitions/ModelB"
  __proto__: Object
__proto__: Object

where the second log after the resolveSchema gives this:

Object {$ref: "#/definitions/ModelB"}

Later on in processModel, the following is what shows the description:

if (!_.isUndefined(cProperty.description)) {
  html += ': ' + '<span class="propDesc">' + cProperty.description + '</span>';
}

Since the description property is stripped off, it sees undefined, and as a result does not show the description. Not sure if there was a reason to strip all properties off here or not, or if only schema needed to be stripped off, but I managed to fix this by making resolveSchema reappend any properties in the old object that isn’t named ‘schema’:

var resolveSchema = module.exports.resolveSchema = function (schema) {
  var resolvedSchema = schema;

  if (_.isPlainObject(schema.schema)) {
    resolvedSchema = resolveSchema(schema.schema);

    for(var key in schema) {
      if(key != "schema") {
        resolvedSchema[key] = schema[key];
      }
    }
  }

  return resolvedSchema;
};

I did notice that resolveSchema is used in a few other places, so not sure if this is the proper fix, but if it is, or close to anyway, I would be happy to contribute a pull request.

I should also mention that the project is using the 1.2 swagger spec. An example json being returned by the api is as follows (only including what I believe is relavent for brevity):

{
    "swaggerVersion": "1.2",
    "models" : {
      "ModelA" : {
        "description" : "",
        "id" : "ModelA",
        "properties" : {
          "modelB" : {
        "description" : "Some description here...",
        "required" : true,
        "type" : "ModelB"
          }
        }
      },
      "ModelB" : {
        //omitted for brevity...
      }
    }
}

I am new to swagger, so if I am misunderstanding something or missing anything in my post, please let me know.

[vlad2]

I think this is still open, as I don’t see any description for a nested object. (In Swagger UI 3.10.0)

It may be related to this: https://stackoverflow.com/questions/43003348/swagger-add-description-with-ref

My object looks like this:

{ “swagger”: “2.0”, … “properties”: { “customerTimezone”: { “description”: “Customer timezone; we use this for squirrels”, “allowEmptyValue”: false, “$ref”: “#/definitions/ZoneId” }, …

[suhasbhatta]

~@Kadams64, we’re no longer working on or supporting the 2.x series of the UI - you’ll need to upgrade to v3 in order to get support in the issue tracker.~

Oops, that is v3. Please open a new issue 😄

Anyone created issue in v3 (Swagger 3.0) ?