add tags to openAPI definitions

source/server/routes/openapi.yml

@@ -1,98 +1,172 @@
 openapi: '3.1.0'
 info:
   title: eCorpus
-  version: '0.0.1'
+  version: '1.0.0'
+  summary: HTTP API for eCorpus
+  description: |
+    This HTTP API provides all necessary routes to access and edit scenes stored on an eCorpus instance under the `/scenes` path.
+    Additionally it provides a number of namespaced utilities
+    for **users** management (`/users`),
+    **authentication** and ACL edition (`/auth`),
+    changes **history** management (`/history`)
+    or gathering scenes under **collections** (`/tags`).
+
+    It provides some webDAV utility routes for the `/scenes` resources 
+    but is far from [Class 1](http://www.webdav.org/specs/rfc4918.html#rfc.section.18.1) Compliance:
+    Only routes that are necessary for proper [Voyager](https://smithsonian.github.io/dpo-voyager/) support are implemented.
+
+
+    Other namespaces tends to adhere to a stricter REST philosophy where possible.
+  contact:
+    name: eCorpus Support
+    url: https://github.com/Holusion/eCorpus
+  license:
+    name: Apache 2.0
+    url: https://www.apache.org/licenses/LICENSE-2.0.html
+  security:
+    - type: http
+      scheme: basic
+    - type: http
+      scheme: bearer
+
 servers:
   - url: https://ecorpus.holusion.com
+tags:
+  - name: scenes
+    desription: |
+      Where all the actual data is stored
+      API design for the `/scenes/*` makes use of the liberal definition of
+      [GET for collections](https://datatracker.ietf.org/doc/html/rfc2518#section-8.4) in the webDAV specification
+      to return well-defined JSON documents for those queries, allowing most use cases to bypass cumbersome PROPFIND queries
+  - name: history
+    description: |
+      history management utilities for the `/scenes` namespace.
+      Scene names in `/history`` directly and uniquely maps to scenes in `/scenes`.
+  - name: tags
+    description: |
+      collections (tags) management routes.
+  - name: users
+    description: Users management
+  - name: auth
+    description: Authentication, access control querying and edition routes. 
 paths:
-# Main data containers
   /scenes:
+    summary: Collection of the scenes stored on this service
     get:
+      tags: [scenes]
       description: |
         get a list of scenes with optional search parameters. Similar to PROPFIND but will return JSON.
         Provides advanced search and pagination semantics
     post:
+      tags: [scenes]
       description: import an archive of scenes to be extracted into the `scenes/` folder
     propfind:
+      tags: [scenes]
       description: fetch all readable content in `scenes/`
   /scenes/{scene}:
     get:
+      tags: [scenes]
       description: get a scene's metadata.
     mkcol:
+      tags: [scenes]
       description: creates a new empty scene. This scene will essentially be invisible until populated
     propfind:
+      tags: [scenes]
       description: fetch the scene's content
     delete:
+      tags: [scenes]
       description: Archives a scene
     post:
+      tags: [scenes]
       description: creates a new scene using attached data
     patch:
+      tags: [scenes]
       description: Edit scene's metadata
   /scenes/{scene}/{file:.*}:
     get:
+      tags: [scenes]
       description: get a file in scene
     put:
+      tags: [scenes]
       description: overwrite the file with new content
     copy:
+      tags: [scenes]
       description: copy a file to another location in the same scene
     move:
+      tags: [scenes]
       description: move a file to another location in the same scene
     delete:
+      tags: [scenes]
       description: archives a file. It is still accessible through the history API
     mkcol:
+      tags: [scenes]
       description: creates a folder in a scene
     propfind:
+      tags: [scenes]
       description: get a file's properties
-# History API is quite linked to the /scenes/** folder. It is however provided in its own namespace
   /history/{scene}:
     get:
+      tags: [history]
       description: get a full history of a scene's modifications
     post:
+      tags: [history]
       description: edit a scene's history
   /history/{scene}/files:
     get:
+      tags: [history]
       description: list all files in the scenes in their current state
-# Tags could be considered as folders containing symlinks to scenes but the required methods are not yet implemented
   /tags:
     get:
+      tags: [tags]
       description: get a list of tags on this server
   /tags/{tag}:
     get:
+      tags: [tags]
       description: get all scenes associated with this tag
-# Users have their own folder of sorts
   /users:
     get:
+      tags: [users]
       description: get a list of registered users
     post:
       description: create a new user
   /users/{uid}:
     delete:
+      tags: [users]
       description: delete a user
     patch:
+      tags: [users]
       description: change a user's data
-# Renamed from /login and /logout, namespaced for clarity
   /auth:
     get:
+      tags: [auth]
       description: get login data
     post:
+      tags: [auth]
       description: log-in to the server
   /auth/login/{username}/link:
     get:
+      tags: [auth]
       description: get a login link for this user
     post:
+      tags: [auth]
       description: generate and send a login link for this user
   /auth/logout:
     post:
+      tags: [auth]
       description: delete this request's credentials
   /auth/access/{scene}:
     get:
+      tags: [auth]
       description: get a scene's access rights
     patch:
+      tags: [auth]
       description: edit a scene's access rights
 # Administrative data. Might contain server configuration routes in the future
   /admin/stats:
     get:
+      tags: [admin]
       description: get server stats
   /admin/mailtest:
     post:
+      tags: [admin]
       description: sends a test email