[Koha-bugs] [Bug 16212] Swagger specification separation and minification

bugzilla-daemon at bugs.koha-community.org bugzilla-daemon at bugs.koha-community.org
Thu Aug 4 11:47:59 CEST 2016


https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=16212

--- Comment #29 from Lari Taskula <larit at student.uef.fi> ---
(In reply to Benjamin Rokseth from comment #28)
> (In reply to Lari Taskula from comment #27)
> > Hey Benjamin, thanks for the interest! I'm glad we share a desire to split
> > our specification :)
> > 
> > (In reply to Benjamin Rokseth from comment #26)
> > > Also I'm not sure of the need to minify swagger at all. If the only reason
> > > is for the online validation, I would argue that the online validation is
> > > the problem. More important is `mojo swagger2 validate`.
> > Our spec in master is not a valid Swagger spec, even if `mojo swagger2
> > validate` says so. Swagger specification does not support a reference whole
> > Definitions-object in swagger.json like this:
> > 
> > "definitions": {
> >   "$ref": "./definitions/index.json"
> > }
> > 
> > That is super annoying, but I think we also want to validate against the
> > online validator because it spots this issue. `mojo swagger2 validate` works
> > (for now), but what if the plugin's validator is updated to consider this
> > type of $ref invalid (as Swagger specification says)? We would have to place
> > all definitions and paths in swagger.json, and at maximum $ref individual
> > paths and definitions to external files, not the whole Paths /
> > Definitions-object.
> > 
> > I think Olli-Antti also encountered some other issues that this minifier
> > fixes. Maybe he can comment more about it.
> > 
> > Btw, I have opened an issue to Swagger2 plugin's GitHub to initiate some
> > more discussion: https://github.com/jhthorsen/swagger2/issues/89
> 
> Lari, I engaged in your discussion at github, but to be sure, are we talking
> about the same thing? I test the swagger definitions at the online swagger
> validator and it obviously fails at relative and URI, as they are not
> resolvable to the validator. This is to be expected, but does not mean the
> definition is invalid. The only way to validate online in any case would be
> to first resolve all refs to one single json document.
> 
> You refer to invalid refs in swagger specifications, but I only find this
> discussion in the swagger-ui
I agree that the online swagger validator is unable to resolve relative
references, but the original issue still exists. You can also write a single
spec file with the problem in online validator, e.g.

{
  "swagger": "2.0",
  "info": { "version": "0.1", "title" : "ref all paths/definitions" },
  "paths": { "$ref": "#/x-def/paths" },
  "definitions": { "$ref": "#/x-def/definitions" },
  "x-def": {
    "definitions": {
      "patron": {
        "type": "object",
        "properties": {
          "borrowernumber": {
            "type": "string",
            "description": "internally assigned user identifier"
          }
        }
      }
    },
    "paths": {
      "/patrons": {
        "get": {
          "responses" : {
            "200": {
              "description": "A list of patrons",
              "schema": {
                "type": "array",
                "items": {
                  "$ref": "#/definitions/patron"
                }
              }
            }
          }
        }
      }
    }
  }
}
online.swagger.io validator will return:
"attribute paths.$ref is not of type `object`",
"attribute definitions.$ref is not of type `object`"

`mojo swagger2 validate` works because it resolves all $refs before validation.
The validation never sees a "$ref". When adjusted to not resolve $refs in our
own spec, I got
[JSON::Validator] type /paths _validate_type_object [/paths: Properties not
allowed: $ref.]
[JSON::Validator] type /definitions/$ref _validate_type_object
[/definitions/$ref: Expected object - got string.]

To make this spec pass validation (both online validator and adjusted case of
JSON::Validator), we need to $ref individual paths and definitions instead,
e.g.:
{
  "swagger": "2.0",
  "info": { "version": "0.1", "title" : "ref individual paths/definitions" },
  "paths": {
    "/patrons": { "$ref": "#/x-def/paths/patrons" }
  },
  "definitions": {
    "patron": { "$ref": "#/x-def/definitions/patron" }
  },
  "x-def": {
    "definitions": {
      "patron": {
        "type": "object",
        "properties": {
          "borrowernumber": {
            "type": "string",
            "description": "internally assigned user identifier"
          }
        }
      }
    },
    "paths": {
      "patrons": {
        "get": {
          "responses" : {
            "200": {
              "description": "A list of patrons",
              "schema": {
                "type": "array",
                "items": {
                  "$ref": "#/definitions/patron"
                }
              }
            }
          }
        }
      }
    }
  }
}

This issue is referred also elsewhere than swagger-ui, here are some links:
https://github.com/mission-liao/pyswagger/issues/53#issuecomment-168872441
(also points to OpenAPI Specification, "@webron: You can reference specific
http verb operations, not full sets of paths.")
swagger-parser comment on the article about splitting spec:
https://github.com/swagger-api/swagger-parser/issues/87#issuecomment-140280055

It's just some of the annoying features in Swagger. It also looks like the
author of Swagger2/OpenAPI plugin has commited this change in the new OpenAPI
plugin
https://github.com/jhthorsen/mojolicious-plugin-openapi/commit/7d804c58eae51b42b3506badd59d4123fb723e8c
and I guess this means that in the future our current spec will not validate
without first resolving all the $refs with (for example) this minifier script.

-- 
You are receiving this mail because:
You are watching all bug changes.
You are the assignee for the bug.


More information about the Koha-bugs mailing list