Nice format for JSON-API

[nickurban]

Hey all,

Thanks for your great work on this. I'm interested in documenting a JSON-API implementation using the jsoinapi-resources gem, and I'm wondering about the fact that attributes and relationships include a lot of repeated boilerplate, e.g. if I wanted to document some attributes on a user object:

with_options scope: [:data, :attributes] do
          parameter :email
end

I end up with a lot of repetition in my parameters, e.g. ["data", "attributes"][email], ["data", "attributes"][first_name], ["data", "attributes"][last_name], etc. rather than just listing e.g. ("email", "first_name", "last_name") and having it be understood that they were all stored in data[attributes] following the JSON-API schema. Is there a way to simplify the presentation?

Thanks,

[sineed]

I want to add that now it is not easy to declare information about relationship. For example, to create a Comment I need to specify its Post and User:

POST /comments

{
  "data": {
    "attributes": {
      text: "Hello"
    },
    "relationships": {
      "post": { "id": 1, "type": "posts" },
      "user": { "id": 2, "type": "users" }
    }
  }
}

And in my request I have:

post "comments" do
  parameter :text, "String", required: true, scope: [:data, :attributes]
  parameter :id, "Integer", required: true, scope: [:data, :relationships, :post, :data]
  parameter :id, "Integer", required: true, scope: [:data, :relationships, :user, :data]

  let(:id) { post.id } # goes in both id parameters

  ...

Maybe it will be convenient to specify a method option of parameter, because now I can't use let mapping feature

[oestrich]

@sineed I think a method addition would be great, that would solve a good deal of recurring issues. If you have the time, I would gladly look at a PR. I am not sure when I'll be able to get to this myself.

[sineed]

@oestrich yes, I think I can find some time to implement this

[sineed]

I found here that I can use the following declaration to accomplish my case:

let(:data_relationships_user_data_id) { user.id }
let(:data_relationships_post_data_id) { post.id }

Looks quite heavy but I think that this is problem of JSON API =)

Also from docs:

The value of scoped parameters can be set with both scoped (let(:order_item_item_id)) and unscoped (let(:item_id)) methods. It always searches for the scoped method first and falls back to the unscoped method.

For me it is more than enough

[sineed]

@oestrich I can make a PR anyway if you wish

[oestrich]

I think having the ability to specify a method is still valuable to have. It would solve issues where someone has client as a parameter, RAD is not happy in those cases. I would still love to see a PR for this.

[kurko]

FYI, in https://github.com/zipmark/rspec_api_documentation/pull/313 (adds APIB support), I had to have a method somehow because APIB specs group docs by that. So I made it work but only for .apib documents though. Adding general support shouldn't be hard.