My biggest question is: Now that you’ve made an awesome API that serves JSON-API, how do you generate client libraries?
I’m loving JSON-API so far. Unfortunately one of the requirements for my project is to somehow describe the API using a machine-readable format, mostly so that client libraries can be automatically generated, although as a plus this would take care of human-readable documentation. That’s not such a big concern because I’m using Rails and
rspec_api_documentation provides great documentation. I need a client library ideally in Scala, but Java would suffice. I see that there are no Java or Scala clients.
So it looks like for describing the API, Swagger might be my best bet. I believe that there is little documentation on describing JSON API using Swagger, and one of the reasons for the lack of docs might be that it’s hard or practically impossible to make a halfway decent description of it. There’s the Swagger Codegen which supports a lot of languages, so making a swagger spec would be a huge win.
With JSON:API, the
included top-level key presents the biggest obstacle here, because it’s an array of disparate types. No matter how I try to do this, including using the
discriminator feature of Swagger (which Swagger Codegen doesn’t support, apparently), I can’t get an accurate description or useful client library. A kludge would be to make additional top level keys like
included_[type2] – the spec says that the root-level document MUST include some things, and MAY include some other things, and there are some mutually exclusive ones (like
errors) but doesn’t explicitly specify that it MUST NOT include other keys.
Can someone clarify whether or not the top-level document MUST NOT include keys that are not specified in the spec?