Explain how the documentaiton type option is matched to class names. Fix...

[jhollinger]

... examples. Per issue #159.

[dblock]

I am confused, does type: API::Entities::Address not work? It should, ultimately it references the same type.

[jhollinger]

I was surprised at the behavior as well. But here's a breakdown of a Cat entity:

expose :pajamas, using: API::Entities::Pajamas, documentation: {type: 'API::Pajamas', desc: "The cat's pajamas"}
shows this in Swagger UI:

{
  "id": 0,
  "name": "",
  "pajamas": {
    "id": 0,
    "color": ""
  }
}

expose :pajamas, using: API::Entities::Pajamas, documentation: {type: 'API::Entities::Pajamas', desc: "The cat's pajamas"} gives this:

{
  "id": 0,
  "name": "",
  "pajamas": "API::Entities::Pajamas"
}

expose :pajamas, using: API::Entities::Pajamas, documentation: {desc: "The cat's pajamas"} gives this:

{
  "id": 0,
  "name": "",
  "pajamas": null
}

expose :pajamas, using: API::Entities::Pajamas, documentation: {type: API::Entities::Pajamas, desc: "The cat's pajamas"} results in that endpoint returning nothing at all to Swagger UI.

[jhollinger]

The sample app I was using to test is at https://gist.github.com/jhollinger/b1b64357a9fc8caec3c2 if you want to confirm or try some different options. But the only value in type I can find that works is "API::Pajamas".

[dblock]

Do you think you can turn that into a spec for grape-swagger? I will look at your example either way.

[jhollinger]

Probably sometime in the next week, yes.

On Wed, Nov 12, 2014, 10:23 AM Daniel Doubrovkine (dB.) @dblockdotorg <
[email protected]> wrote:

Do you think you can turn that into a spec for grape-swagger? I will look
at your example either way.

—
Reply to this email directly or view it on GitHub
https://github.com/tim-vandecasteele/grape-swagger/pull/171#issuecomment-62734751
.

[dblock]

Bump.

[jhollinger]

Got a bit preoccupied. Anyway, I changed an existing spec that was artificially hiding the top-level module with Grape::Entity.entity_name. I then added a few more checks to verify that all the types started with MyAPI::.

While overriding entity_name to get rid of a top-level module certain works, I think it's non-obvious, especially since it's missing from some of the examples in the README.

[dblock]

Thanks, merging.