jsonapi.org specification format?

[JohnSmall]

I'm following the JSON-API specification http://jsonapi.org/ but the format generated by swagger_schema doesn't put things in that format. So the json generated in the documentation doesn't match what's actually produced.

How can I get the model schemas to match the schemas for the JSON-API spec?

[fotinakis]

What is different?

[JohnSmall]

The JSON-API specification http://jsonapi.org/format/ adds quite a bit to the payload. It's useful because it's information about relationships and such like. But it also means that the JSON schema generated by Swagger-blocks doesn't match what you get back for a call to the API and you certainly can't use the Swagged-UI to 'try it now', because if you do then it sends JSON that isn't valid according to the spec and therefore a POST/PATCH will fail.

I think I'll have to make the code changes myself. But not today.

[fotinakis]

I'm also the author of https://github.com/fotinakis/jsonapi-serializers in case you want to check that out. I use both JSON-API and Swagger but unfortunately not in the same project, so I haven't built an integration for the two, I'd be curious to know if there's an easy path.

[onewheelskyward]

Hmm, looks like I'm in the same boat, too. Nice work on jsonapi-serializers btw.

[onewheelskyward]

Well, I ended up doing this the hard way for now, I'll take a look at how to make it simpler in the future:

swagger_schema :Thing do
    property :data do
      key :type, :object
      property :type do
        key :type, :string
        key :description, "The type of the object, in this case 'things'"
      end
      property :id do
        key :type, :integer
        key :description, 'Thing id'
      end
      property :attributes do
        key :type, :object
        key :required, [:title]
        property :title do
          key :type, :string
        end
      end
    end
end

[bastianlb]

@onewheelskyward any update on how you handle swagger for the JSONAPI spec? this is rather tedious to do for every resource.

[JohnSmall]

Yes it is tedious for every resource. I've tried a few things to DRY up my code but it's a mess.

And now I'm stuck. I can't find a way to create a swagger document that describes objects in an array. E.g.

{ data:[ some_object, another_object ] }

Any ideas anyone?

[saverio-kantox]

@JohnSmall what I did for JSONAPI is to write functions that create the boilerplate, and then pass the rest as params:

def swagger_jsonapi_schema(resource_name, attributes, relationships, &block)
  swagger_schema resource_name do
    property :data, type: :object do
      property :type, type: :string, description: "The type of the resource"
      property :id, type: :string, description: "The unique resource identifier"
      property :attributes, type: :object do
        attributes.each { |attr| ... }
      end
   end
end

and similarly for other boilerplate. The magic of ruby...

For the objects in an array, you have to do something like

property: :data, type: :array do
  key :items, :'$ref' => :SomethingElse
end

(or define it inline)