[Koha-bugs] [Bug 15126]=?UTF-8?Q?=20REST=C2=A0API?=: Use newer version of Swagger2

[bugzilla-daemon at bugs.koha-community.org]

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

--- Comment #26 from Olli-Antti Kivilahti <olli-antti.kivilahti at jns.fi> ---
(In reply to Julian Maurice from comment #17)
> I just tested minifySwagger.pl and something bothers me : it resolves all
> "$ref", meaning the "minified" file will be larger than the sum of all files
> it comes from if the same "$ref" is used at least twice.
> 
> Is it possible resolve only "$ref" that point to different files ? So we
> keep the idea of a (small) single minified file and let the client resolve
> the other refs.

There are some issue with this approach. Firstly, if you want to have reusable
reference contents, they probably must reside under the "Definitions Object",
and the "Definitions Object" only accepts Schemas/Objects, so we cannot define
reusable primitive data types, such as biblionumber.
{ type => 'String',
  description => 'descr'
}

Atleast I didn't figure out how to do it.

Maybe you could add an extra level of nesting under the "Definitions Object"
"x-primitive-definitions": {
  "biblionumber": {
    type => 'Integer',
    description => 'descr'
  }
}

but that might break any automatic Swagger2-tools.

Also the way references are dereferenced is part of the core
Mojolicious::Plugin::Swagger2-functionality and I am not so sure how the
original author will like that change. I guess it would be nice to have and
even doable, but it might be a really difficult algorithm to implement, which
makes a complex system even more complex.

The reason I implemented this approach is that external Swagger2-tools (like
Swagger2 UI) doesn't resolve those references well, or was it that they dont
reference at all (at the point of writing).

I am not concerned about any repetition in the Swagger2-definition in Koha, tho
you never know how it might affect us in the future.


Anyway. I am currently working on implementing CORS-support for the
Swagger2-API, because we need it now. This certainly is a challenge :)


Also. We moved the
/definitions/index.json
to
/definitions.json

When you reference a definition, you had to write the reference like this:
"$ref": "/definitions/index.json#/borrowernumber"

now you can write the reference more easy:
"$ref": "/definitions.json#/borrowernumber"

Anyway you can find our newest Swagger2-definition from here:
https://github.com/KohaSuomi/kohasuomi/tree/kohasuomi3.16/api/v1/swagger
https://renki.vaarakirjastot.fi/api/v1/doc/


It took us quite some time to refactor to that model + a lot of testing :)
But we are more interested in following the community model. However our API is
a product of months of work and continuous self-improvement so I can say with
confidence that we are taking the right route.

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