Interest in a JSON API-conformant example specification?

Hi Swagger Team,

I’m working with an API that conforms to the JSON API spec, which has a JSON Schema definition that I have translated into Swagger YAML data type definitions (with a few bits like validations commented out that either the Swagger spec or some current tool implementations don’t support).

Working with this is exposing several issues for me in swagger-codegen, for example, that appear to be things the Swagger specification supports but the tools do not yet. additionalProperties: false is one example.

I’m also finding that code generated from swagger-codegen templates sometimes makes limited assumptions based on testing exclusively with Petstore, like model definitions only being objects and not arrays or primitives. The included construct in JSON API is an array, for instance, so a model of that causes issues right off the bat with generated ObjC code.

These are issues with swagger-codegen and I will and am reporting them there. But I’m wondering if a JSON API-based example might be welcomed in swagger-spec where it would be continuously validated and hopefully more likely to be adopted by the various tool projects for tests. If JSON API achieves popularity it might be a common use case, and an example spec will exercise some more advanced features that Swagger supports like polymorphic models.

If there’s interest in this I’ll prepare a PR for an example spec. If you think it’d be a better fit somewhere else (like just in swagger-codegen), I’m all ears, but I thought it might have worth as a more complex test case for several of the tool projects.

[InteNs]

in elixir/phoenix someone made a jsonapi module for swagger: https://github.com/xerions/phoenix_swagger

[MrTrick]

Hi @stevenxryan,
My apologies - since spending a heap more time with swagger I’ve discovered all sorts of horrible things… Like how the phrase “swagger uses an extended subset of json-schema” really means “swagger breaks a heap of json-schema things for no good reason”.

For example, external references? Swagger-editor and many other swagger parsers do not understand them. You’ll have to inline them.