object properties in resource view show description of object and not description of the property about dapperdox HOT 7 OPEN

I've a test case for this somewhere too, thanks for the example. There has been quite a lot of work and discussion around the context of property descriptions, and I was sure we'd got this right (for example, we have lots of resources that contain addresses which are defined as a standard, reusable definition. Each address instance is different though, so the description of each address property is taken from the property and not the referenced definition.

I can confirm I can reproduce with your example. Will investigate, as we agree with you, that is the way it should be. There might be a subtle difference in our specifications. We will see...

from dapperdox.

If you define the second property as follows (with the $ref within an items member), then you get the result you expect (for second).

        "second": {
          "type": "object",
          "description": "second property",
          "items" : {
               "$ref": "#/definitions/MyObject"
          }
        }

items appears only mandatory for arrays (and outside of in in body). To be honest, the specification isn't that explicit, and parsers generally seem to manage. We wonder if using an items member for no array references is strictly wrong. Either way, DapperDox is not working for specifications that do not have items and that is incorrect.

Fixing....

EDIT: Actually, we're convinced "items": { "$ref": .... } is wrong for all but array types.

from dapperdox.

The problem seems to stem from go-openapi, the specification parser used by DapperDox. Without the "items":{} wrapper around "$ref": ... we do not get a Description returned by go-openapi.

I've opened an issue over there, so we'll see what they say. We've sent them quite a detailed report. go-openapi/spec#22

from dapperdox.

We've got the answer. JSON schema states that other properties in an object with $ref need to be ignored. http://json-schema.org/latest/json-schema-core.html#rfc.section.7 So what go-openapi and thus DapperDox is doing is correct.

However, wrapping $ref in an items:{} block is also (technically) wrong, as items should only be used for arrays. Because DapperDox needs to support it for arrays, it also "works" for object.

The correct solution (advised by the go-openapi guys) is this:

{
  "first": {
    "allOf" : [
      {
        "type": "object",
        "description": "first property"
      },
      {
        "$ref": "#/definitions/MyObject"
      }
    ]
  }
}

Basically, merge the partial schema object, containing type and description with the referenced object, thus adding description to MyObject (type is mandatory, so must be there).

However, the current release of DapperDox doesn't process this correctly because it expects each element of the allOf array to be a complete schema object, each with properties. We just hadn't seen or expected this use case.

We're working on a more complete solution, so will leave this issue open.

from dapperdox.

Great, thanks!

from dapperdox.

Still working on this. It's a little complicated!

from dapperdox.

I was testing some other schema and I found a solution with works:

{
  "first": {
    "type": "object",
    "description": "first property"
    "allOf" : [
      {
        "$ref": "#/definitions/MyObject"
      }
    ]
  }
}

I'm not sure if this is according to the spec but it is rendered as expected in dapperdox.

from dapperdox.