json-api does not appear to be supported

[adhamhf]

Using swagger-ui 3.0.10 (currently use dev HEAD) I'm not able to get json-api to work correctly.

The request and response content types are displayed as application/vnd.api+json which is what my server is set to, so that's good.

However, the Example Value is structured as a JSON object instead of JSON-API. A simple fix for this would be to take the current example value and put it into a data object:

data: {
   attributes: {
      // what is currently showing up as the Example Value.
   }
}

A related issue is that "Try it out" does not work, because its not sending properly formatted json-api data.

There are several javascript json-api implementations, include one in redux. http://jsonapi.org/implementations/#client-libraries-javascript

[webron]

@adhamhf can you provide a sample spec to reproduce the issue? As long as it's still JSON and it's described properly, there shouldn't be an issue with sending it.

[adhamhf]

@webron, if I copy and paste a valid JSON-API request into the try it field then it works correctly. I suppose I assumed the provided example would work too, or at least be in the proper JSON-API format.

[webron]

Right, but that suggests your spec is inaccurate. If you can provide it, with the expected structure, I could look into it.

[adhamhf]

It's going to be difficult for me to share the spec. From looking at the "Example Value" in the UI I can see it does not match up with the the request that works. I assume I need to work on the spec and make them match?

Also, are you saying that the "Example Value" should be a properly formatted JSON-API object? My server will reject anything that's not 100% correct JSON-API so I need the swagger-ui to show JSON-API...

[webron]

JSON-API is just a format. I don't know if you can or cannot describe it using Swagger, as I'm not well-versed in it. You need to make sure that the model you have in the spec describes the format as you want it to appear. Without seeing the spec and an example expected model, I can't help you any further. If you can't share your spec, even in private, I'm afraid there's not much else I can do.

[adhamhf]

Based on reading some github issues (below ) I have some followup questions.

Do the paths in my swagger spec have to be JSON-API specific? Meaning that my parameters and responses all have to be defined to include a data, includes or error objects?

My spec is not setup like this right now and I think that's the problem:

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

This also means that for each if I have web clients that want JSON-API and mobile clients that want JSON I will have to have two separate specs for each end point? I guess I thought swagger was data exchange format agnostic. I expected swagger-ui to produce a valid example payload based on the content type I selected.

https://medium.com/@knightstickc/building-an-api-with-swagger-json-api-and-rails-part-2-8f9691e3de04
OAI/OpenAPI-Specification#476
OAI/OpenAPI-Specification#519

[webron]

Swagger just describes your API, whether it follows your own standards or others. Not everything can be described using Swagger. Since you won't share your spec to show the problem, there's really nothing else I can offer in terms of support.

[adhamhf]

@webron So you aren't even going to answer my questions? That's not very nice.

[webron]

I'm trying to help you to resolve the issue. We have a process for it. I can't answer questions for all the questions that are being addressed. I don't have the time to read into JSON-API, the different aspects and whatnot. If you'd like to get this specific issue, I'd be happy to assist - I need a spec and an example.

You think it's not very nice? It's your right. I think it's not very nice repeatedly ignoring my request in order to assist you, not is it very nice of you to not respect my time.

If you have general questions about the spec, that's fine - this is not the place.

[adhamhf]

@webron
I have attached a simple swagger.json file the reproduces the issue. To summarize if I use "Try it out" with the default "Example Value", my server throws an exception because the the default "Example Value" is not in the correct JSON-API format my server requires.

swagger.json.zip

[adhamhf]

If it helps any, here's the curl that I copied out of the swagger-ui and the response.

curl -X POST "http://localhost:8080/v1/shoes" -H "accept: application/vnd.api+json" -H "content-type: application/vnd.api+json" -d "{ \"id\": \"string\", \"shoeSize\": {}, \"shoeType\": \"string\"}" | json_pp
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100   282    0   227  100    55  23296   5644 --:--:-- --:--:-- --:--:-- 25222
{
   "errors" : [
      {
         "links" : null,
         "id" : null,
         "detail" : null,
         "status" : "400",
         "source" : {
            "parameter" : "/v1/shoes",
            "pointer" : "pointy"
         },
         "code" : "aCode",
         "meta" : null,
         "title" : "Resource must contain at least one of 'data', 'error' or 'meta' nodes"
      }
   ]
}

[webron]

It looks like you're describing only the object itself without the entire envelop. You'd need to describe that too in order for it to work.

[adhamhf]

Shouldn't swagger-ui be agnostic about the envelop? Or choose the appropriate envelop based on the content type popup? If the swagger spec has to describe the envelop for swagger-ui to work correctly then I'm not sure how the swagger spec would work plain JSON.

[webron]

It is agnostic, which is why you need to specify everything. It doesn't care if you use your own constructs, JSON-API, JSON-LD, XML, or whatever. If you want something to be passed, you need to describe it.

[adhamhf]

Really, I think this is talking too much about the swagger spec. This is really about swagger-ui. If swagger-ui used consumes/produces to determine the format of the data this wouldn't be an issue. I'm used to using Swagger with JPA and Ember. We generate models and controllers from the spec but use JSON-API as our transport mechanism. That's all worked great without having to put anything about JSON-API into the spec. Its only when we have started to use the swagger-ui tool that we have started to think about putting JSON-API into the spec.

I would like you to reopen this issue and consider put it to the team as a feature request. There's really no reason to have to format my swagger spec for JSON-API, it will actually cause more problems because then I'm locked into just supporting JSON-API and can't use JSON.

Additional thought on why this should be a feature request... The swagger spec we are using is generated by SpringFox based on swagger annotations. These annotations don't care what the format of the message is, they just specify what is/is not in the message. I think this another reason why the swagger-ui tool should use consumes/produces.

[webron]

It looks like you don't fully grasp the goal of the spec and the swagger tools around it. If it's not supported by the spec, we're not going to add support for it in the tools. As you pointed out, we might end up adding a wrapper support in the spec - but this is not going to happen in the upcoming version. For now, the only way for you to use the tool is to fully describe the wrapper as part of the requests and potentially the responses. JSON-API is JSON, I don't see the problem.

[adhamhf]

It is likely I don't grasp the goals since I'm not a member of the project. It's likely I'm trying to be helpful while being a PITA...

Now that I understand that goal I think it should be reconsidered. I actually thing encoding the data exchange format in the spec means that your spec is no longer agnostic. You are now tied to a specific format instead of being able to use any format, or multiple formats. Also, it means the swagger generators have to know about the format, or discard the format when generating models and controllers. Generally speaking, models and controllers shouldn't care about the format of the data going over the wire.

Where would be a better place to open an issue to start a discussion about that?

[fehguy]

I really think you're missing something. If you're sending JSON, then it's supported if you can describe your structure. If you can't describe the JSON, then it won't work. Please consider reading the spec repo again.

[adhamhf]

I think I understand what you're saying about the spec.

Here's a related question that I think will help explain my thinking. In the swagger spec a path has to be unique. A path can have consumes and produces arrays that state which media types are acceptable. Suppose I have a path that consumes json-api and json. How do I describe both of these formats in my spec?

[webron]

You keep referencing json-api and json as different things. JSON-API is not a serialization format, it's a definition of a structure. JSON is a serialization format. JSON-API uses JSON to serialize its structure.

It's true that you can define different media types, and be more specific - this is 'pure' JSON, or this is a JSON-API struct. In the next version of the spec, you'll be able to define a different schema per media type that you define for the spec, so you could define the difference between the JSON and JSON-API constructs as you see them.

However, you would still need to define the enveloping structure - the spec does not, and will not, care about specific implementations out there (such as JSON-API) because those pop up all the time, and die out, and have versions, and simply cannot be maintained. If your 'data' part is the same for the JSON and JSON-API variants, you could use one to compose the other.

[adhamhf]

Thanks all. I appreciate your time. I don't think I've been able to convey the advantages of my proposal correctly, or maybe even the proposal itself. The downsides of text based communication.

[cemsbr]

I'm not sure whether my problem is included in your discussion. If I change application/json to application/vnd.api+json (JSON API content type), the example is not rendered anymore. Could swagger-ui treat vnd.api+json exactly like json and render the example the same way?