Fails to load due to null http operations in spec file

[csuich2]

If a spec contains null http operations, Swagger UI fails to load due to missing null checks in two places:

Uncaught TypeError: Cannot read property 'parameters' of null (swagger-client.js:332)
Uncaught TypeError: Cannot read property 'tags' of null (swagger-client.js:686)

I came across this issue as my API is build & served with Jersey/JAX-RS and our serialization strategy includes serializing nulls.

I have identified a fix and will submit a PR shortly.

...
paths: {
  "/myapi": {
    "get": { ... },
    "put": { ... },
    "post": null,
    "delete": null,
    ...
  }
}

[webron]

Technically, that's not a valid spec.

[fehguy]

Yes, we should try, though, to not fail when we see null. @whitlockjc this is probably an easy fix.

[csuich2]

I read through https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md and didn't se anything that would specify whether a null value for an operation was valid or invalid. Did I miss something in the spec that defines this?

[webron]

@csuich2 - what @fehguy mentioned is true, we shouldn't fail on such things. Generally, null values are not supported across the spec. If you feel it should be clarified, please open an issue on swagger-spec and I'll take care of it. Thanks.

[whitlockjc]

@webron is right. If you look at the JSON Schema, it allows a pathItemObject of which null is not a valid structure. If you do not want to support those HTTP verbs for that path, just omit them. If some other tool is generating this invalid Swagger document, file a bug.

@fehguy is right as well. swagger-js should be resilient to these types of things and I will look into it soon.

[csuich2]

The reason the HTTP verbs are null is because of our APIs serialization. We explicitly serialize null values using GSON for all of our API responses which may not be a common practice, but I'm not sure I would label it as uncommon either.

[whitlockjc]

Common or not, it is not valid. In the end, Swagger is a documentation format and it has rules in place. These rules are documented in the Swagger Specification and they are enforced structurally via the Swagger JSON Schema. Your explicit serialization is violating one of the rules, it's as simple as that. In the end, I will update swagger-js so that it will not fail when it encounters these but if you start using other tooling, like tools that validate your Swagger documents, you will run into this again I'm sure.

[csuich2]

Thanks for talking this through, everyone! I've opened an issue for some clarification on the spec project.

Thanks!