From 5d7da34f43a975e5b8a1eb45bca942f5813b0739 Mon Sep 17 00:00:00 2001 From: Tomas Cohen Arazi Date: Wed, 21 Apr 2021 12:18:31 -0300 Subject: [PATCH] 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 Signed-off-by: Martin Renvoize Signed-off-by: Kyle M Hall --- Koha/REST/V1.pm | 2 +- api/v1/swagger/swagger.json | 28 ---------------------------- api/v1/swagger/swagger.yaml | 32 ++++++++++++++++++++++++++++++++ 3 files changed, 33 insertions(+), 29 deletions(-) delete mode 100644 api/v1/swagger/swagger.json create mode 100644 api/v1/swagger/swagger.yaml diff --git a/Koha/REST/V1.pm b/Koha/REST/V1.pm index 6f17c4cea4..6e3d3d50b8 100644 --- a/Koha/REST/V1.pm +++ b/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") } ); diff --git a/api/v1/swagger/swagger.json b/api/v1/swagger/swagger.json deleted file mode 100644 index d1c80e4f26..0000000000 --- a/api/v1/swagger/swagger.json +++ /dev/null @@ -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" - } -} diff --git a/api/v1/swagger/swagger.yaml b/api/v1/swagger/swagger.yaml new file mode 100644 index 0000000000..aa66681944 --- /dev/null +++ b/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. -- 2.24.3 (Apple Git-128)