[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