Configurable depth of properties in "Response Schema"

[geld0r]

In the "Response Schema" section of an API call, the whole response (including nested entities) is shown, e.g. like this:

Response Schema
Status Code 200
Name          | Type        | Required | Description
--            | --          | --       | --
anonymous     | [Animals]   | false    | No description
» comment     | string      | false    | Optional note
» kittens     | [Kitten]    | false    | A list of kittens
--            | --          | --       | --
»» name       | string      | false    | e.g. "Mr Meowz"

The UI correctly shows clickable links to the entitites (Animals and Kitten). If interested, a user can jump to the schema description if additional details are required. In the response schema section the nested properties may be unnecessary though. The link to the schema should be enough, as the information is duplicated here.

It would be great if the depth in the response schema was configurable, i.e. show every property (as this is done right now) or only expand nested entities to depth one (only show property "comment" and "kittens") or depth two (show "comment", "kittens" and "name"), etc.

Can this already be achieved? There are other depth related options, but none of them seem to have an effect on this. If its not already possible, can this be extended?

[MikeRalphson]

See also #122 which appears to be related.

[MikeRalphson]

Widdershins v3.3.0 has a new --shallowSchemas option which limits expansion of schema properties past $refs. With this option, and judicious use of $refs to named schemas, you should be able to achieve a more readable result.

If feedback is good, --shallowSchemas may become the default in v4.0.0.

[geld0r]

Sounds great, I'll try this out!

[geld0r]

I tried --shallowSchemas (from v3.4.0) but found the following issues:

1. In the response section, the nested model entity showed up as expected, but a single property of that nested entity did show up afterwards with nesting (»). Maybe this occurs because of the nested entity having another nested entity? Example in swagger.yml:

definitions:
  Kitten:
  type: object
    properties:
      comment:
        type: string
      toys:
        type: array
        items:
          $ref: '#/definitions/Toy'
      userId:
        type: string

For one of the API calls that returns a list of Kittens, the expected result is to have only one entry in the response table and that is for the list of Kittens. However there is a second entry for "userId" which is indented with ». A Kitten has more properties, but I guess that the nested array (which comes directly before this property) has to do with it.

2. In the schema section, the property list for one schema ends after the first list of nested properties is given (e.g "toys" above). Other properties on the same level are not given anymore, even though they should not be omitted. This seems to occur everytime an entity contains a list.

Both issues could have to do with $ref being used in nested entities as well. Is this information enough to reproduce this on your side?

[geld0r]

@MikeRalphson: Did you have a chance already to look at this?

[MikeRalphson]

I've extended your example a bit and can reproduce this section of the report:

In the schema section, the property list for one schema ends after the first list of nested properties is given (e.g "toys" above). Other properties on the same level are not given anymore, even though they should not be omitted. This seems to occur everytime an entity contains a list.

I'll look at fixing that and see if that is the only issue or if it sheds a light on part 1 of your issue.

[MikeRalphson]

Hi @geld0r are you able to test from the GitHub repo, or do you need a release published to npm? What I've done might only be a partial fix, and until I've got time to write loads of tests for schema rendering, it's also possible I might have broken --shallowSchemas in some other way...

[geld0r]

So far I've only used versions released to npm. How can I test development versions?

[MikeRalphson]

Clone the repository into a fresh directory, change into it and npm i. Then node widdershins.js should run that version.

[MikeRalphson]

@geld0r did you find any time to test this?

[geld0r]

Sadly not yet. A solution is still required though, I simply didn't have any time. I'll try to get back to it next week.

[MikeRalphson]

Thanks, it's much appreciated.

[rssteffey]

Hey, @MikeRalphson !

I was having a similar issue with my nested objects and found this issue.

If I apply --shallowSchemas in my generation before your #107 commits above, I get the cut-off version where any fields after my compacted object are excluded from the list

Unfortunately, after those commits, the shallowSchema option seems to stop working entirely and once again includes all the $ref object properties

Let me know if you want me to test any more cases or need my schema definitions!

[MikeRalphson]

@rssteffey thanks for testing! It seems my nervousness about those commits was justified. Reverted. Really going to have to write some tests for the schemaToArray function... :cry: