Document login and logout endpoints

lib/www/server/spec/openapi.yaml

@@ -1323,3 +1323,43 @@ paths:
                         application/geo+json:
                             schema:
                                 $ref: "#/components/schemas/GeoJSONFeature"
+
+
+    /login:
+        post:
+            summary: Request a user token.
+            description: Users are identified by a username and a password. Usernames do not need to be unique, meaning that the same username can have different passwords and each user/password combination can have its own role. For instance, a user could have one password for everyday use and another to log in as administrator.
+            tags: [ "login" ]
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            type: object
+                            properties:
+                                user:
+                                    type: string
+                                    description: User name to log in as
+                                password:
+                                    type: string
+                                    description: Password corresponding to given user and requested role
+            responses:
+                "204":
+                    description: Login successful. The token is returned in a `Set-Cookie` header.
+
+
+    /logout:
+        get:
+            summary: Log out (GET alternative).
+            description: |
+                Visiting this endpoint will cause the authorisation cookie `JWT` to be overwritten with an expired cookie, hopefully causing user agents to forget the previous token.
+
+                Note that this does not necessarily mean that the user *will* be logged out. The only way to truly log out, other than removing the user from the system, is for the client to forget its token or let it expire.
+
+                Note that the user may be logged back in automatically on the next API request if they are connecting from an authorised network or host.
+
+            tags: [ "login" ]
+        post:
+            summary: Log out (POST alternative).
+            description: Same as its `GET` counterpart. It does not require a body and if one is sent it will be ignored.
+            tags: [ "login" ]