From d14631593a066323d99f00bb8859d4a138469831 Mon Sep 17 00:00:00 2001
From: Martin Renvoize <martin.renvoize@ptfs-europe.com>
Date: Mon, 23 Oct 2023 16:19:18 +0100
Subject: [PATCH] Bug 29523: (follow-up) Adding documentation to swagger.yaml
Content-Type: text/plain; charset=utf-8

Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>

Signed-off-by: Marcel de Rooy <m.de.rooy@rijksmuseum.nl>
---
 api/v1/swagger/swagger.yaml | 23 +++++++++++++++++++++--
 1 file changed, 21 insertions(+), 2 deletions(-)

diff --git a/api/v1/swagger/swagger.yaml b/api/v1/swagger/swagger.yaml
index 351f796c56..cdca970837 100644
--- a/api/v1/swagger/swagger.yaml
+++ b/api/v1/swagger/swagger.yaml
@@ -767,9 +767,20 @@ info:
     name: Koha Development Team
     url: https://koha-community.org/
   description: |
-    ## Introduction
+    ## Background
 
-    This API is documented in **OpenAPI format**.
+    The API supports two sets of endpoints, one targetted at library staff and the other at at library users.
+
+    Those endpoints under the `/public` path are aimed at delivering functionality tailored to library users and offer
+    a more restricted set of functions, overrides and data in thier responses for data privacy and library policy
+    reasons. Many of these endpoints do not require authentication for fetching public data, though an authenticated
+    session will expose additional options and allow users to see more data where it is part of their own record.
+
+    All other endpoints are targetted at the staff interface level and allow for additional functionality and a more
+    unrestricted view of data.  These endpoints, however, have a level of redaction built in for resources that the
+    api consumer should not have access to.  For example, user data for users who do not belong to the same library
+    or library group of your api user will be reduced to just minimum neccesary for a valid response. Object keys will
+    be consistent for all responses, but their values may be removed depending on access.
 
     ## Authentication
 
@@ -782,6 +793,14 @@ info:
     Both _Basic authentication_ and the _OAuth2_ flow, need to be enabled
     by system preferences.
 
+    ## Authorization
+
+    The API uses existing user profiles to restrict access to resources based on user permissions and the library the
+    API user is assigned to.  This may result, at times, in resources being returned in a redacted form with all keys
+    present but sensative values nulled.
+
+    We do not yet support OAuth Scopes or the Authorization Code grant flow.
+
     ## Errors
 
     The API uses standard HTTP status codes to indicate the success or failure
-- 
2.30.2