Merge pull request #262 from nulib/4072-document-auth-routes

Document /auth/* routes

.github/workflows/docs.yml

@@ -26,15 +26,12 @@ jobs:
       - uses: actions/checkout@v2
       - uses: actions/setup-python@v2
         with:
-          python-version: 3.9
-      - uses: abatilo/actions-poetry@v2
-        with:
-          poetry-version: 1.4.2
+          python-version: 3.10
       - name: Install dependencies
-        run: poetry install
+        run: pip install -r requirements.txt
         working-directory: ./docs
       - name: Build docs
-        run: poetry run mkdocs build --clean
+        run: mkdocs build --clean
         working-directory: ./docs
       - name: Determine correct deploy domain for environment
         run: sed -i s/API_HOST/${HOSTNAME}/g docs/site/spec/openapi.*

README.md

@@ -162,11 +162,11 @@ In a nutshell:
 2. Edit the Markdown files in the `docs/docs` directory.
 3. To run `mkdocs` locally and preview your work:
    ```shell
-   pip install poetry # only has to be done once
    cd docs
-   poetry install
+   python -m venv ./.venv
+   pip install -r requirements.txt
    sg open all 8000
-   poetry run mkdocs serve -a 0.0.0.0:8000
+   mkdocs serve -a 0.0.0.0:8000
    ```
    Docs will be accessible at http://[DEV_PREFIX].dev.rdc.library.northwestern.edu:8000/
 

docs/docs/spec.md

@@ -1,4 +1 @@
-<iframe width="1400" height="600" src="../spec/openapi.html"></iframe>
-[full window :octicons-link-external-16:](../spec/openapi.html)
-
-[Here](../spec/openapi.json) is the OpenAPI spec.
+!!swagger ./spec/openapi.yaml!!

docs/docs/spec/openapi.yaml

@@ -22,13 +22,85 @@ tags:
   - name: Search
     description: >
       Endpoints for searching the index.
+  - name: Authentication
+    description: >
+      Endpoints for authenticating and obtaining information about the current user.
   - name: OAI-PMH
     description: >
       Endpoint implementing the Open Archives Initiative Protocol for Metadata Harvesting (OAI-PMH).
       As OAI-PMH is not a REST protocol, it is difficult to represent using OpenAPI/Swagger documentation.
       For full documentation and examples, please see the [official specification](https://www.openarchives.org/pmh/).
       Note: all 'from' and 'until' query parameters are required to follow the format: 'YYYY:MM:DDThh:mm:ss.ffffffZ'. If you do not need nanosecond precision for your request, then pad the date with zero values, e.g. '2023-01-13T00:00:00.000000Z'
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT  
+security:
+  - anonymous: []
+  - bearerAuth: []
 paths:
+  /auth/login:
+    get:
+      operationId: getAuthLogin
+      description: Initiate a user login
+      tags:
+        - Authentication
+      parameters:
+        - name: goto
+          in: query
+          required: false
+          description: URL to redirect to after login
+          schema:
+            type: string
+            format: uri
+            default: /auth/whoami
+      responses:
+        302:
+          description: A redirect to the login page
+  /auth/token:
+    get:
+      operationId: getAuthToken
+      description: Obtain a bearer auth token for the logged in user
+      tags:
+        - Authentication
+      parameters:
+        - name: ttl
+          in: query
+          required: false
+          description: TTL in seconds for the token expiration
+          schema:
+            type: number
+            minimum: 0
+            maximum: 604800
+            default: 86400
+      responses:
+        200:
+          description: Authentication token response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  token:
+                    type: string
+                  expires:
+                    type: string
+                    format: date-time
+  /auth/whoami:
+    get:
+      operationId: getAuthWhoami
+      description: Obtain information about the logged in user
+      tags:
+        - Authentication
+      responses:
+        200:
+          description: User details
+          content:
+            application/json:
+              schema:
+                type: object
   /collections:
     get:
       operationId: getCollections

docs/mkdocs.yml

@@ -24,6 +24,8 @@ edit_uri: blob/main/docs/docs/
 plugins:
   - macros
   - search
+  - render_swagger:
+      allow_arbitrary_locations : true
 markdown_extensions:
   - admonition #adds ability to have custom highlight boxes with !!!
   - codehilite:
@@ -42,8 +44,8 @@ markdown_extensions:
       alternate_style: true
   - pymdownx.tilde
   - pymdownx.emoji:
-      emoji_index: !!python/name:materialx.emoji.twemoji
-      emoji_generator: !!python/name:materialx.emoji.to_svg
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
       options:
         custom_icons:
           - overrides/.icons