Browse Source

Bug 28189: Move swagger file to YAML format

This patch changes the base OpenAPI file (swagger.json) into YAML. The
motivation for this, is adding more documentation, in Markdown.

JSON doesn't accept multiline strings, so this seems like a good move
for readability.

To test:
1. Verify your API is functional
2. Apply this patch
3. Repeat 1
=> SUCCESS: No changes, really
4. Point your browser to /api/v1/.html
=> SUCCESS: Some nicely formatted description of the API can be seen. It
includes information about x-koha-library.
5. Sign off :-D

Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>

Signed-off-by: Kyle M Hall <kyle@bywatersolutions.com>

Signed-off-by: Jonathan Druart <jonathan.druart@bugs.koha-community.org>
21.05.x
Tomas Cohen Arazi 9 months ago
committed by Jonathan Druart
parent
commit
3c16e0110e
  1. 2
      Koha/REST/V1.pm
  2. 28
      api/v1/swagger/swagger.json
  3. 32
      api/v1/swagger/swagger.yaml

2
Koha/REST/V1.pm

@ -79,7 +79,7 @@ sub startup {
$spec = $validator->bundle(
{
replace => 1,
schema => $self->home->rel_file("api/v1/swagger/swagger.json")
schema => $self->home->rel_file("api/v1/swagger/swagger.yaml")
}
);

28
api/v1/swagger/swagger.json

@ -1,28 +0,0 @@
{
"swagger": "2.0",
"info": {
"title": "Koha REST API",
"version": "1",
"license": {
"name": "GPL v3",
"url": "http://www.gnu.org/licenses/gpl.txt"
},
"contact": {
"name": "Koha Development Team",
"url": "https://koha-community.org/"
}
},
"basePath": "/api/v1",
"paths": {
"$ref": "paths.json"
},
"definitions": {
"$ref": "definitions.json"
},
"parameters": {
"$ref": "parameters.json"
},
"x-primitives": {
"$ref": "x-primitives.json"
}
}

32
api/v1/swagger/swagger.yaml

@ -0,0 +1,32 @@
---
swagger: 2.0
basePath: /api/v1
paths:
$ref: paths.json
definitions:
$ref: definitions.json
parameters:
$ref: parameters.json
x-primitives:
$ref: x-primitives.json
info:
title: Koha REST API
version: 1
license:
name: GPL v3,
url: http://www.gnu.org/licenses/gpl.txt
contact:
name: Koha Development Team
url: https://koha-community.org/
description: |
## Introduction
This API is documented in **OpenAPI format**.
## Special headers
### x-koha-library
This optional header should be passed to give your api request a library
context; If it is not included in the request, then the request context
will default to using your api comsumer's assigned home library.
Loading…
Cancel
Save