It implements only the "client credentials" flow with no scopes
support. API clients are tied to an existing patron and have the same
permissions as the patron they are tied to.
API Clients are defined in $KOHA_CONF.
Test plan:
0. Install Net::OAuth2::AuthorizationServer 0.16
1. In $KOHA_CONF, add an <api_client> element under <config>:
<api_client>
<client_id>$CLIENT_ID</client_id>
<client_secret>$CLIENT_SECRET</client_secret>
<patron_id>X</patron_id> <!-- X is an existing borrowernumber -->
</api_client>
2. Apply patch, run updatedatabase.pl and reload starman
3. Install Firefox extension RESTer [1]
4. In RESTer, go to "Authorization" tab and create a new OAuth2
configuration:
- OAuth flow: Client credentials
- Access Token Request Method: POST
- Access Token Request Endpoint: http://$KOHA_URL/api/v1/oauth/token
- Access Token Request Client Authentication: Credentials in request
body
- Client ID: $CLIENT_ID
- Client Secret: $CLIENT_SECRET
5. Click on the newly created configuration to generate a new token
(which will be valid only for an hour)
6. In RESTer, set HTTP method to GET and url to
http://$KOHA_URL/api/v1/patrons then click on SEND
If patron X has permission 'borrowers', it should return 200 OK
with the list of patrons
Otherwise it should return 403 with the list of required permissions
(Please test both cases)
7. Wait an hour (or run the following SQL query:
UPDATE oauth_access_tokens SET expires = 0) and repeat step 6.
You should have a 403 Forbidden status, and the token must have been
removed from the database.
8. Create a bunch of tokens using RESTer, make some of them expires
using the previous SQL query, and run the following command:
misc/cronjobs/cleanup_database.pl --oauth-tokens
Verify that expired tokens were removed, and that the others are
still there
9. prove t/db_dependent/api/v1/oauth.t
[1] https://addons.mozilla.org/en-US/firefox/addon/rester/
Signed-off-by: Josef Moravec <josef.moravec@gmail.com>
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Signed-off-by: Jonathan Druart <jonathan.druart@bugs.koha-community.org>
This patch introduces two functions to the patrons endpoint:
- _to_api
- _to_model
This are in charge of field mappings in order to comply with the
guidelines.
Koha::REST::V1:Auth is adjusted to handle 'patron_id' as well. 'borrowernumber'
handling is kept until the existing endpoints get updated.
To test:
- Apply the patches
- Run:
$ kshell
k$ prove t/db_dependent/api/v1/*.t
=> SUCCESS: Tests pass!
- Sign off :-D
Signed-off-by: Josef Moravec <josef.moravec@gmail.com>
Signed-off-by: Nick Clemens <nick@bywatersolutions.com>
Signed-off-by: Kyle M Hall <kyle@bywatersolutions.com>
Signed-off-by: Jonathan Druart <jonathan.druart@bugs.koha-community.org>
This patch removes the $ref occurences for borrowernumber in not
patron-specific endpoints. 'borrowernumber' is still used on them, but as a
hardcoded parameter. The param rename will happen on a separate bug for
each endpoint.
Signed-off-by: Josef Moravec <josef.moravec@gmail.com>
Signed-off-by: Nick Clemens <nick@bywatersolutions.com>
Signed-off-by: Kyle M Hall <kyle@bywatersolutions.com>
Signed-off-by: Jonathan Druart <jonathan.druart@bugs.koha-community.org>
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Signed-off-by: Benjamin Rokseth <benjamin.rokseth@kul.oslo.kommune.no>
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Signed-off-by: Josef Moravec <josef.moravec@gmail.com>
Signed-off-by: Jonathan Druart <jonathan.druart@bugs.koha-community.org>
This patch refactors the original work so it implements the controllers
and the spec using Mojolicious::Plugin::OpenAPI, and OpenAPI for the specification.
It removes the ability for patrons without permissions to edit their own data or their
guarantee's. This will be moved to a patron modification requests endpoint for simplicity.
It makes use of bugs 19410 and 19686 and their dependencies to deal with parameters handling,
query building and pagination.
Tests are adapted.
To test:
- Apply this patches and the dependencies
- Run:
$ kshell
k$ prove t/db_dependent/api/v1/patrons.t
=> SUCCESS: Tests pass!
- Sign off :-D
Sponsored-by: ByWater Solutions
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Signed-off-by: Benjamin Rokseth <benjamin.rokseth@kul.oslo.kommune.no>
Signed-off-by: Josef Moravec <josef.moravec@gmail.com>
Signed-off-by: Jonathan Druart <jonathan.druart@bugs.koha-community.org>
This patch adds support for add, edit and delete patrons via REST API.
GET /api/v1/patrons Get patron list from params
GET /api/v1/patrons/<borrowernumber> Get single patron
POST /api/v1/patrons Create a new patron
PUT /api/v1/patrons/<borrowernumber> Update data about patron
DEL /api/v1/patrons/<borrowernumber> Delete a patron
Revised Test plan:
1) Apply this patch
2) Run tests perl t/db_dependent/api/v1/patrons.t
3) Add a user with proper rights to use the REST API
4) play with your favourite REST client (curl/httpie, etc.):
Authenticate with the user created above and get a CGISESSION id.
Use the CGISESSION to add, edit and delete patrons via the API.
5) Use PUT /patrons/<borrowernumber> for a patron without borrowers
flag. This should go into pending patron modification status and
needs to be accepted by a librarian.
Please note there is no validation of body input in PUT/POST other
than branchcode,category,userid,cardnumber.
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Signed-off-by: Benjamin Rokseth <benjamin.rokseth@kul.oslo.kommune.no>
Signed-off-by: Josef Moravec <josef.moravec@gmail.com>
Signed-off-by: Jonathan Druart <jonathan.druart@bugs.koha-community.org>
This patch implements the changes required by the cities endpoint RFC
[1].
It uses the objects.search helper, and relies on bug 19686.
To test:
- Apply the patches
- Compare the spec with the RFC (api/v1/swagger/definitions/city.json)
=> SUCCESS: It makes sense
- Run:
$ kshell
k$ prove t/db_dependent/api/v1/cities.t
=> Tests pass!
- Sign off :-D
Signed-off-by: Claire Gravely <claire.gravely@bsz-bw.de>
Signed-off-by: Kyle M Hall <kyle@bywatersolutions.com>
Signed-off-by: Jonathan Druart <jonathan.druart@bugs.koha-community.org>
Fields 'address' and 'city' have been maybe nullable by this bug. This
patch makes them nullable on the API as well.
To test:
- Run:
$ kshell
k$ prove t/db_dependent/api/v1/patrons.t
=> FAIL: Tests fail (randomly) when address or city are set to null by
TestBuilder.
- Apply this patch
- Run:
k$ prove t/db_dependent/api/v1/patrons.t
=> SUCCESS: Tests pass!
- Sign off :-D
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Signed-off-by: Jonathan Druart <jonathan.druart@bugs.koha-community.org>
There is something wrond here, the userenv is no set and so we cannot
user search_limited.
Should we set the userenv or filter on the libraries using
libraries_where_can_see_patrons?
WAITING FOR FEEDBACK HERE.
Signed-off-by: Signed-off-by: Jon McGowan <jon.mcgowan@ptfs-europe.com>
Signed-off-by: Jonathan Druart <jonathan.druart@bugs.koha-community.org>
Test plan:
1/ Use your usual "REST testing" tool to place a title-level hold with
an itemtype. The request should look like this:
POST /api/v1/holds
{
"borrowernumber": 1234,
"biblionumber": 456,
"branchcode": "CPL",
"itemtype": "A"
}
2/ Check that the hold was placed and the itemtype is correctly selected
3/ prove t/db_dependent/api/v1/holds.t
Signed-off-by: Benjamin Rokseth <benjamin.rokseth@kul.oslo.kommune.no>
Signed-off-by: Josef Moravec <josef.moravec@gmail.com>
Signed-off-by: Jonathan Druart <jonathan.druart@bugs.koha-community.org>
This patch re-adds some parameters I left out during some rebasing tasks
and ended up on a separate patchset (bug 18731).
The introduced parameters definitions are only used on endpoint definitions
that implement (at least) pagination. No need to test them here but easier
adding them here than on a patch implementing a new enpoint, which would become
a dependency for other endpoints.
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Signed-off-by: Jonathan Druart <jonathan.druart@bugs.koha-community.org>
This patch moves the current endpoint implementation from Swagger2 to
the OpenAPI plugin.
It also takes advantage of the overloaded Koha::Illrequest::TO_JSON method
which has now the option to embed what's needed for the REST api.
The path spec is adjusted to fit OpenAPI, and some minor fixes are
applied:
- Missing 'metadata' query param
- 'ill' permissions should be required instead of 'borrowers'
- Full test coverage
To test:
- Apply this patch
- Run:
$ kshell
k$ prove t/db_dependent/api/v1/illrequests.t
=> SUCCESS: Tests pass!
- Sign off :-D
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Signed-off-by: Magnus Enger <magnus@libriotech.no>
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Signed-off-by: Benjamin Rokseth <benjamin.rokseth@kul.oslo.kommune.no>
Signed-off-by: Jonathan Druart <jonathan.druart@bugs.koha-community.org>
This Commit is at the heart of adding an interlibrary loans framework
for Koha. The framework does not prescribe a particular workflow.
Instead it provides a general framework that can be extended &
implemented by individual backends whose responsibility it is to
implement a specific workflow.
The module is largely self-sufficient: it adds new tables to the Koha
database and touches only a few files in the Koha source tree.
Primarily, we add our files to the Makefile and the koha-conf.xml,
define ill paths for the REST API, and introduce links from the main
intranet, opac pages & user permissions.
Outside of this we simply add new files & functionality.
Signed-off-by: Magnus Enger <magnus@libriotech.no>
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Signed-off-by: Benjamin Rokseth <benjamin.rokseth@kul.oslo.kommune.no>
Signed-off-by: Jonathan Druart <jonathan.druart@bugs.koha-community.org>
Trying to clarify some of the descriptions.
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Signed-off-by: Jonathan Druart <jonathan.druart@bugs.koha-community.org>
This patch introduces an /acquisitions/vendors endpoint.
To test:
- Apply the patch
- Run:
$ sudo koha-shell kohadev
k$ prove t/db_dependent/api/v1/acquisitions_vendors.t
=> SUCCESS: Tests pass
- Sign off :-D
Sponsored-by: ByWater Solutions
Signed-off-by: Matthias Meusburger <matthias.meusburger@biblibre.com>
Signed-off-by: Kyle M Hall <kyle@bywatersolutions.com>
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Signed-off-by: Jonathan Druart <jonathan.druart@bugs.koha-community.org>
operationId has the following documentation:
"Unique string used to identify the operation. The id MUST be unique among all
operations described in the API."
This patch modifies operationIds to be unique accross our API operations.
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Signed-off-by: Jonathan Druart <jonathan.druart@bugs.koha-community.org>
Before this file grows, we should sort it alphabetically.
To test:
1. prove t/db_dependent/api/v1
Signed-off-by: Josef Moravec <josef.moravec@gmail.com>
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Signed-off-by: Jonathan Druart <jonathan.druart@bugs.koha-community.org>
Mojolicious::Plugin::OpenAPI does not support x-mojo-around action. This patch
removes it from our specification document.
Signed-off-by: Olli-Antti Kivilahti <olli-antti.kivilahti@jns.fi>
Signed-off-by: Josef Moravec <josef.moravec@gmail.com>
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Signed-off-by: Jonathan Druart <jonathan.druart@bugs.koha-community.org>
Also
- adding some missing and new response definitions into Swagger spec.
- fixing failing tests due to Bug 17932's change of boolean values
To test:
1. prove t/db_dependent/api/v1/holds.t
Signed-off-by: Olli-Antti Kivilahti <olli-antti.kivilahti@jns.fi>
Signed-off-by: Josef Moravec <josef.moravec@gmail.com>
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Signed-off-by: Jonathan Druart <jonathan.druart@bugs.koha-community.org>
Also:
- adding some missing and new response definitions into Swagger spec.
To test:
1. prove t/db_dependent/api/v1/cities.t
Signed-off-by: Olli-Antti Kivilahti <olli-antti.kivilahti@jns.fi>
Signed-off-by: Josef Moravec <josef.moravec@gmail.com>
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Signed-off-by: Jonathan Druart <jonathan.druart@bugs.koha-community.org>
Also:
- adding some missing and new response definitions into Swagger spec.
- fixing failing test due to Bug 17932's change of boolean values
To test:
1. prove t/db_dependent/api/v1/patrons.t
Signed-off-by: Olli-Antti Kivilahti <olli-antti.kivilahti@jns.fi>
Signed-off-by: Josef Moravec <josef.moravec@gmail.com>
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Signed-off-by: Jonathan Druart <jonathan.druart@bugs.koha-community.org>
Test plan:
prove api/v1/swagger/definitions/patron.json
must return green
Signed-off-by: Lee Jamison <ldjamison@marywood.edu>
swagger/definitions.t test returns green
Recently, there's been a major fix on the REST api swagger spec,
which involved fixing boolean values so they are actually booleans
and Koha::Object was extended to handle that.
While the swagger spec for this endpoint got fixed, such is not the case
with the implementation (the controller class).
This patch fixes this situation by:
- Specifying boolean properties as boolean in the schema file
- Fixes the controller so it returns Koha::Hold objects instead of the
hashref returned by GetReserve, which is wrong.
- Better (than empty) descriptions are added to 'suspend',
'suspend_until' and 'lowestPriority' on the spec.
To test:
- Run:
$ sudo koha-shell kohadev
k$ cd kohaclone
k$ prove t/db_dependent/api/v1/holds.t
=> FAIL: Tests fail, mostly due to error 500 results.
- Apply this patch
- Run:
k$ prove t/db_dependent/api/v1/holds.t
=> SUCCESS: Tests pass!
- Sign off :-D
This can also be tested using any interface for REST apis.
Note: This endpoint lacks several of the new guidelines and is not
complete (there's no GET for single holds, etc). It is also missing
exception handling. There are probably
other bug reports for that, just thought it was worth mentioning.
Followed test plan and this patch worked as intended
Signed-off-by: Alex Buckley <alexbuckley@catalyst.net.nz>
Signed-off-by: Kyle M Hall <kyle@bywatersolutions.com>
This patch changes current Swagger definitions for patrons and holds to have
data types corresponding to column data types in their database tables.
To test:
1. GET http://yourlibrary/api/v1/patrons/YYY where YYY is existing borrowernumber
2. Observe that numbers / integers are in string data type.
3. Apply this patch
4. Repeat step 1.
5. Observe that numbers / integers are now actually numbers / integers.
Signed-off-by: Josef Moravec <josef.moravec@gmail.com>
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Signed-off-by: Kyle M Hall <kyle@bywatersolutions.com>
Routes for holds have tags called "borrowers". We should use "patrons" instead
in order not to have both (endpoints for patrons already add "patrons").
This patch changes the tags from borrowers to patrons in:
GET /holds
POST /holds
Signed-off-by: Josef Moravec <josef.moravec@gmail.com>
Signed-off-by: Katrin Fischer <katrin.fischer@bsz-bw.de>
Signed-off-by: Kyle M Hall <kyle@bywatersolutions.com>
The swagger file does not consider borrowers.updated_on as a nullable
value, it should
Test plan:
0/ Do not apply this patch
1/ update borrowers set updated_on=null;
2/ prove t/db_dependent/api/v1/patrons.t
=> Fail
3/ Apply this patch
4/ prove t/db_dependent/api/v1/patrons.t
=> green
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Signed-off-by: Kyle M Hall <kyle@bywatersolutions.com>
This patch makes the patron swagger definition match the DB schema.
To test:
- Run:
$ prove t/db_dependent/api/v1/swagger/definitions.t
=> FAIL: 'lastseen' field is not declared in the swagger definition
- Apply the patch
- Run:
$ prove t/db_dependent/api/v1/swagger/definitions.t
=> SUCCESS: Tests pass!
- Sigh off :-D
Sponsored-by: ByWater Solutions
Signed-off-by: Hector Castro <hector.hecaxmmx@gmail.com>
All tests pass successfuly
Signed-off-by: Lari Taskula <lari.taskula@jns.fi>
Fixed a typo: seed -> seen
Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
Signed-off-by: Kyle M Hall <kyle@bywatersolutions.com>
This followup alters a few area's to be aligned more closely with
RESTfull best practices:
* PUT should always be full objects, and not partial updates (use PATCH
for partials)
* Validate query parameters instead of blindly passing them to the model
* Functional Change: Convert filter params from 'equality' to 'starts with'
matching
* Update tests to check for swagger validation errors instead of koha exceptions
* Mark 'id' as readOnly so swagger may prevent, via validation, id
changes.
Signed-off-by: Jonathan Druart <jonathan.druart@biblibre.com>
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Signed-off-by: Kyle M Hall <kyle@bywatersolutions.com>
This patch adds the swagger definitions for the /cities endpoint
Signed-off-by: Josef Moravec <josef.moravec@gmail.com>
Signed-off-by: Jonathan Druart <jonathan.druart@biblibre.com>
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Signed-off-by: Kyle M Hall <kyle@bywatersolutions.com>
The swagger specification file is currently being minified adding
manual steps to release management and restful api route development.
The minification is not required; The deferenced version of the
specification is now internally validated at runtime and relavant errors
output and the dereferenced schema has been made publically available at
/api/v1/spec, so it can be copy&pasted into validation tools
Test Plan
1) Apply patch
2) Ensure api routes still function (applying the /cities patch might be
helpful)
3) Ensure /api/v1/spec page exists (it should be the de-referenced
swagger.json file)
Signed-off-by: Claire Gravely <claire_gravely@hotmail.com>
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Signed-off-by: Brendan Gallagher <brendan@bywatersolutions.com>
To test:
1. Run t/db_dependent/api/v1/holds.t
2. Run t/db_dependent/api/v1/patrons.t
Signed-off-by: Benjamin Rokseth <benjamin.rokseth@kul.oslo.kommune.no>
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Signed-off-by: Kyle M Hall <kyle@bywatersolutions.com>
Define 'x-koha-permission' for the Swagger2 Operation Object, to automatically
authorize against the required permissions.
This way we immediately tell the API consumer in the Swagger2-definition, which
permissions are needed to access defined resources.
Also we don't need to maintain permissions in multiple locations and we can build
a smart testing framework to help a lot in creating tests for the new REST API.
Signed-off-by: Benjamin Rokseth <benjamin.rokseth@kul.oslo.kommune.no>
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Signed-off-by: Kyle M Hall <kyle@bywatersolutions.com>
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Signed-off-by: Benjamin Rokseth <benjamin.rokseth@kul.oslo.kommune.no>
Signed-off-by: Kyle M Hall <kyle@bywatersolutions.com>
borrowernumberQueryParam shouldn't be required as also changed in Bug 16271.
To test:
1. Don't apply the patch yet, but first minify Swagger and run
t/db_dependent/api/v1/holds.t
2. Observe that some tests fail with response code 400 when expecting 200.
3. Apply patch and minify Swagger
4. Run t/db_dependent/api/v1/holds.t
5. Observe that tests pass.
Signed-off-by: Benjamin Rokseth <benjamin.rokseth@kul.oslo.kommune.no>
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Signed-off-by: Kyle M Hall <kyle@bywatersolutions.com>
This patch separates Swagger-specifications and the minifySwagger.pl from other
api-files by moving specifications & minifier into api/v1/swagger.
Signed-off-by: Olli-Antti Kivilahti <olli-antti.kivilahti@jns.fi>
My name is Olli-Antti Kivilahti and I approve this commit.
We have been using the Swagger2.0-driven REST API on Mojolicious for 1 year now
in production and I am certain we have a pretty good idea on how to work with
the limitations of Swagger2.0
We participated in the development of the Mojolicious::Plugin::Swagger and know
it well. We have made an extension to the plugin to provide full CORS support
and have been building all our in-house features on the new REST API.
Signed-off-by: Johanna Raisa <johanna.raisa@gmail.com>
My name is Johanna Räisä and I approve this commit.
We have been using Swagger2.0-driven REST API in production successfully.
Signed-off-by: Benjamin Rokseth <benjamin.rokseth@kul.oslo.kommune.no>
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Signed-off-by: Kyle M Hall <kyle@bywatersolutions.com>
Since we have defined some basic x-primitives in x-primitives.json, we can now
start to reuse them in our currently defined objects.
To test:
1. Apply patch
2. Run minifySwagger.pl
3. Validate your Swagger specifications
4. Observe that validation passes
Signed-off-by: Olli-Antti Kivilahti <olli-antti.kivilahti@jns.fi>
My name is Olli-Antti Kivilahti and I approve this commit.
We have been using the Swagger2.0-driven REST API on Mojolicious for 1 year now
in production and I am certain we have a pretty good idea on how to work with
the limitations of Swagger2.0
We participated in the development of the Mojolicious::Plugin::Swagger and know
it well. We have made an extension to the plugin to provide full CORS support
and have been building all our in-house features on the new REST API.
Signed-off-by: Johanna Raisa <johanna.raisa@gmail.com>
My name is Johanna Räisä and I approve this commit.
We have been using Swagger2.0-driven REST API in production successfully.
Signed-off-by: Benjamin Rokseth <benjamin.rokseth@kul.oslo.kommune.no>
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Signed-off-by: Kyle M Hall <kyle@bywatersolutions.com>
Currently it is not possible to define multiple types for primitive definitions
in /definitions/*. If you try to use the following
"firstname": {
"type": ["string", "null"],
"description": "patron's first name"
}
in definitions.json, online.swagger.io validator will not validate it:
{"messages":["attribute definitions.firstname.type is not of type `string`"]}
One way to get around this issue is to extend definitions with custom
"x-primitives" object, where we will define all reusable primitive definitions.
To test:
1. Add the "firstname" example above to definitions.json
2. Run minifySwagger.pl
3. Validate your specification
4. Observe that error with description mentioned above is given
5. Apply patch
6. Repeat step 2 and 3
7. Observe that validation passes
Signed-off-by: Olli-Antti Kivilahti <olli-antti.kivilahti@jns.fi>
My name is Olli-Antti Kivilahti and I approve this commit.
We have been using the Swagger2.0-driven REST API on Mojolicious for 1 year now
in production and I am certain we have a pretty good idea on how to work with
the limitations of Swagger2.0
We participated in the development of the Mojolicious::Plugin::Swagger and know
it well. We have made an extension to the plugin to provide full CORS support
and have been building all our in-house features on the new REST API.
Signed-off-by: Johanna Raisa <johanna.raisa@gmail.com>
My name is Johanna Räisä and I approve this commit.
We have been using Swagger2.0-driven REST API in production successfully.
Signed-off-by: Benjamin Rokseth <benjamin.rokseth@kul.oslo.kommune.no>
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Signed-off-by: Kyle M Hall <kyle@bywatersolutions.com>
These definitions had indentation of 4 spaces, while rest of the specification
uses 2 spaces. This patch simply maintains the consistency in indentations and
provides no other modifications to code.
Signed-off-by: Olli-Antti Kivilahti <olli-antti.kivilahti@jns.fi>
My name is Olli-Antti Kivilahti and I approve this commit.
We have been using the Swagger2.0-driven REST API on Mojolicious for 1 year now
in production and I am certain we have a pretty good idea on how to work with
the limitations of Swagger2.0
We participated in the development of the Mojolicious::Plugin::Swagger and know
it well. We have made an extension to the plugin to provide full CORS support
and have been building all our in-house features on the new REST API.
Signed-off-by: Johanna Raisa <johanna.raisa@gmail.com>
My name is Johanna Räisä and I approve this commit.
We have been using Swagger2.0-driven REST API in production successfully.
Signed-off-by: Benjamin Rokseth <benjamin.rokseth@kul.oslo.kommune.no>
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Signed-off-by: Kyle M Hall <kyle@bywatersolutions.com>
The borrowernumber as a query parameter should be defined in parameters.json
in order to allow its reusability.
To test:
1. Apply patch
2. Run minifySwagger.pl
3. Validate swagger.min.json in online.swagger.io/validator/debug?url=url_to+
_your_swagger_min_json or your local swagger-api/validator-badge validator
4. Observe that validation passes
Signed-off-by: Olli-Antti Kivilahti <olli-antti.kivilahti@jns.fi>
My name is Olli-Antti Kivilahti and I approve this commit.
We have been using the Swagger2.0-driven REST API on Mojolicious for 1 year now
in production and I am certain we have a pretty good idea on how to work with
the limitations of Swagger2.0
We participated in the development of the Mojolicious::Plugin::Swagger and know
it well. We have made an extension to the plugin to provide full CORS support
and have been building all our in-house features on the new REST API.
Signed-off-by: Johanna Raisa <johanna.raisa@gmail.com>
My name is Johanna Räisä and I approve this commit.
We have been using Swagger2.0-driven REST API in production successfully.
Signed-off-by: Benjamin Rokseth <benjamin.rokseth@kul.oslo.kommune.no>
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Signed-off-by: Kyle M Hall <kyle@bywatersolutions.com>
Parameters and paths should be split in our Swagger specification, because
otherwise swagger.json would become messy with all the paths and their
further specification in the same file. Also parameters should be split
for the same reason.
Instead of using index.json for definitions, parameters and paths, we define
new files "definitions.json", "parameters.json" and "paths.json" in order to
simplify the references. If we kept using index.json and try to reference
"/definitions/error.json" from "/paths/holds.json", reference would be
"../definitions/index.json#/error" instead of now simplified version,
"../definitions.json#/error".
Here is the proposed structure:
.
├── swagger.json
├── definitions.json
├── paths.json
├── parameters.json
├── definitions
│ └── error.json
│ └── patron.json
├── parameters
│ └── patron.json
├── paths
│ └── patrons.json
├── minifySwagger.pl
└── swagger.min.js
The swagger.json paths, definitions and parameters will look as follows:
...
"paths": {
"$ref": "paths.json"
},
"definitions": {
"$ref": "definitions.json"
},
"parameters": {
"$ref": "parameters.json"
}
...
A problem with splitting specification into multiple files directly from
swagger.json (e.g. "paths": { "$ref": "paths.json" }) is that it is not
following the Swagger specification and an error will be thrown by the
Swagger-UI default validator (online.swagger.io/validator).
To overcome this problem, we use the minifySwagger.pl script from Buug 16212.
This allows the developers to work with the structure introduced in this patch
thus allowing developers to split the specification nicely, and still have a
valid Swagger specification in the minified swagger.min.json.
To test:
-2: Apply the minifier-patch in Buug 16212.
-1: Make sure you can validate your specification with Swagger2 validator at
online.swagger.io/validator/debug?url=url_to_swaggerjson, or install it
locally from https://github.com/swagger-api/validator-badge.
1. Don't apply this patch yet, but first validate swagger.json
with swagger.io-validator (or your local version, if you installed it)
2. Observe that validation errors are given
3. Run minifySwagger.pl
4. Validate swagger.min.json with the validator you used in step 1
5. Observe that validation passes and we overcame the invalid specification
problem in swagger.min.json
6. Apply this patch
7. Run minifySwagger.pl
8. Repeat step 4
9. Observe that validation passes with new structure
10. Run REST tests at t/db_dependents/api/v1
(11. Study the new structure of our Swagger specifications :))
Signed-off-by: Olli-Antti Kivilahti <olli-antti.kivilahti@jns.fi>
My name is Olli-Antti Kivilahti and I approve this commit.
We have been using the Swagger2.0-driven REST API on Mojolicious for 1 year now
in production and I am certain we have a pretty good idea on how to work with
the limitations of Swagger2.0
We participated in the development of the Mojolicious::Plugin::Swagger and know
it well. We have made an extension to the plugin to provide full CORS support
and have been building all our in-house features on the new REST API.
Signed-off-by: Johanna Raisa <johanna.raisa@gmail.com>
My name is Johanna Räisä and I approve this commit.
We have been using Swagger2.0-driven REST API in production successfully.
Signed-off-by: Benjamin Rokseth <benjamin.rokseth@kul.oslo.kommune.no>
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Signed-off-by: Kyle M Hall <kyle@bywatersolutions.com>
