Interest in a JSON API-conformant example specification?

[ches]

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.

[webron]

Thanks for reaching out, @ches.

JSON API is a design paradigm whereas Swagger is a description format. Just trying to set the expectations that the two have different goals, and it is not the general goal of Swagger to describe a specific API design format (it can certainly be done, we're just trying to remain agnostic).

Examples are welcome to join, of course, and that could be a good to the project. If you'd like, you can link us to your examples prior to submitting a PR so we'd get a better feel of what you'd want to add.

The issue with additionalProperties: false is actually somewhat different and may require clarification in the spec about the intent, but we'll have to discuss that separately.

[ches]

Thanks @webron.

JSON API is a design paradigm whereas Swagger is a description format. Just trying to set the expectations that the two have different goals, and it is not the general goal of Swagger to describe a specific API design format (it can certainly be done, we're just trying to remain agnostic).

Yep, I understand that clearly. In fact I think this description of a JSON API service is proving to be a nice example that in can be done, and it might even help people understand the distinction better if there were eventually example Swagger descriptions of APIs following a few of the well-known paradigms like HAL as well.

The actual service I've been working on is private at this time, but the description of the fundamental JSON API elements is trivial to extract. In the next day or two I'll add some example models and resources around it, perhaps adapting Petstore's would make sense.

I'll share a Gist here when I get to it.

[webron]

Great, thanks. I'll reply regarding the additionalProperties over at the codegen.

[ches]

Oh, and I'd be curious to be linked to the discussion about additionalProperties: false if you open it somewhere. I suspect it might have something to do with Swagger not having the same goals of providing validation as JSON Schema but I suppose I'll hear your thoughts in the appropriate forum.

[webron]

Here is the appropriate forum, but since the issue came up in codegen, we'll go over it there and move it here when done.

[ream88]

Hey @ches, any chance to see the gist? 😊

[pablorsk]

I'm very interested on this. I use JsonApi and Swagger but the documentation is not match the schemas. [swagger-php in my case ;)]

[adamhathcock]

👍

[onemanstartup]

I struggle to with json-api

      responses:
        200:
          description: get article
          schema:
            $ref: '#/definitions/Article'

To wrap this in object data I need to do this

        200:
          description: get article
          schema:
            type: object
            properties:
              data:
                "$ref": "#/definitions/Article"

and to array in object

          schema:
            type: object
            properties:
              data:
                type: array
                items:
                  "$ref": "#/definitions/Article"

It will be great to abstract those things to be more composable. What do you think @webron ?

[webron]

@onemanstartup - please take a look at #519.

[MrTrick]

@onemanstartup within the limitations of 2.0 I would suggest that you keep #/definitions/Article as a valid JSON-API resource and define e.g. a #/responses/responseOne-Article and #/responses/responseMany-Article:

"definitions": {
    "responseOne": {
        "allOf": [{ "$ref": "jsonapi.org-schema.json#/definitions/success" }],
        "properties": { 
            "data": { "type": "object" } 
        }
    },
    "responseMany": {
        "allOf": [{ "$ref": "jsonapi.org-schema.json#/definitions/success" }],
        "properties": { 
            "data": { "type": "array" } 
        }
    },  
    "Article": {
        "allOf": [{ "$ref": "jsonapi.org-schema.json#/definitions/resource" }],
        ...
    }
},
"responses": {
    "responseOne-Article": {
        "allOf": [{ "$ref": "#/definitions/responseOne" }],
        "properties": { 
            "data": { "$ref": "#/definitions/Article" } } 
        }
    },
    "responseMany-Article": {
        "allOf": [{ "$ref": "#/definitions/responseMany" }],
        "properties": {
            "data: { 
                "items": { "$ref": "#/definitions/Article" } 
            }
        }
    }
}

So, an operation returning a single Article would have "schema": { "$ref": "#responses/responseOne-Article" }

Yes it is a little tedious to set up, but it keeps semantic meaning, clear hierarchy of schema, and allows the Article resource schema to be used separately for eg a body parameter.

[x-st3v3n]

When I try Mr Trick's suggestion (above) I get swagger errors - none of the relative references in the external jsonn-api schema file cannot be resolved.

How to fix?

Sample error below is for unresolvable #/definitions/data, but the same error occurs for all jsonapi defintiions in the jsonapi schema file i.e. resources, meta, links, pagination etc.

Swagger Error

Reference could not be resolved: #/definitions/data
Details
Object
code: "UNRESOLVABLE_REFERENCE"
message: "Reference could not be resolved: #/definitions/data"
path: Array [7]
error: "JSON Pointer points to missing location: #/definitions/data"
level: 900
type: "Swagger Error"
description: "Reference could not be resolved: #/definitions/data"
lineNumber: -1

[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.

[x-st3v3n]

Ah well, thanks for the insight. Saves me from eating any more time. Unfortunate, but at least now I know it's not just me being daft !

I had a quick crack at adding the Jsonapi scenario inline, but got a bunch of errors.

Any idea if it can work, or better not to waste time?My other option is to not include the Jsonapi schematic, instead just copy/plagiarise the bits I really need - a subset and none of the fancier stuff.

[MrTrick]

@stevenxryan I've got something duct-taped together that swagger seems for the most part to accept: https://gist.github.com/MrTrick/2a46a65eee763b2f5a9c

[x-st3v3n]

Thanks for sharing, much appreciated.

And I do like the well-named dumbDown().

[aCandidMind]

Just for the case someone needs a json:api -> swagger solution or some inspiration:
the json:api solution for Ruby called jsonapi_suite has autogenerated documentation (incl. swagger.json), so they got it working and I was able to use that feature without hassle so far.
https://jsonapi-suite.github.io/jsonapi_suite/how-to-autodocument

I guess the most relevant code is here:
https://github.com/jsonapi-suite/jsonapi_swagger_helpers/tree/master/lib/jsonapi_swagger_helpers

But it relies on its own concepts to generate the swagger.json. Mainly resource models which can also define request parameters such as

class PostResource < ApplicationResource
  # Used for associating this resource with a given input.
  # This should match the 'type' in the corresponding serializer.
  type :posts

  # === Allow ?filter[name] query parameter ===
  allow_filter :name do |scope, value|
    scope.where('name LIKE ?', value)
  end

and payloads definitions that you make for your tests such as this:

  key(:enabled, Boolean)
  key(:status, String)

[InteNs]

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

[handrews]

If someone wants to contribute more/better examples covering more API styles, we welcome them, but given that it's been 6 years since the last comment and it's not something the OpenAPI maintainers need to track, I'm going to close this.