Add /user routes to openapi schema

app/commands.py

@@ -1,7 +1,7 @@
 import csv
 import functools
 import itertools
-import os
+from os import getenv
 import uuid
 from datetime import datetime, timedelta
 
@@ -9,6 +9,7 @@ import click
 import flask
 from click_datetime import Datetime as click_dt
 from flask import current_app, json
+from notifications_python_client.authentication import create_jwt_token
 from notifications_utils.recipients import RecipientCSV
 from notifications_utils.statsd_decorators import statsd
 from notifications_utils.template import SMSMessageTemplate
@@ -86,7 +87,7 @@ class notify_command:
 
         # in the test environment the app context is already provided and having
         # another will lead to the test db connection being closed prematurely
-        if os.getenv('NOTIFY_ENVIRONMENT', '') != 'test':
+        if getenv('NOTIFY_ENVIRONMENT', '') != 'test':
             # with_appcontext ensures the config is loaded, db connected, etc.
             decorators.insert(0, flask.cli.with_appcontext)
 
@@ -111,7 +112,7 @@ def purge_functional_test_data(user_email_prefix):
 
     users, services, etc. Give an email prefix. Probably "notify-tests-preview".
     """
-    if os.getenv('NOTIFY_ENVIRONMENT', '') not in ['development', 'test']:
+    if getenv('NOTIFY_ENVIRONMENT', '') not in ['development', 'test']:
         current_app.logger.error('Can only be run in development')
         return
 
@@ -726,7 +727,7 @@ def validate_mobile(ctx, param, value):
 @click.option('-s', '--state', default="active")
 @click.option('-d', '--admin', default=False, type=bool)
 def create_test_user(name, email, mobile_number, password, auth_type, state, admin):
-    if os.getenv('NOTIFY_ENVIRONMENT', '') not in ['development', 'test']:
+    if getenv('NOTIFY_ENVIRONMENT', '') not in ['development', 'test']:
         current_app.logger.error('Can only be run in development')
         return
 
@@ -746,3 +747,10 @@ def create_test_user(name, email, mobile_number, password, auth_type, state, adm
     except IntegrityError:
         print("duplicate user", user.name)
         db.session.rollback()
+
+@notify_command(name='create-admin-jwt')
+def create_admin_jwt():
+    if getenv('NOTIFY_ENVIRONMENT', '') != 'development':
+        current_app.logger.error('Can only be run in development')
+        return
+    print(create_jwt_token(current_app.config['SECRET_KEY'], current_app.config['ADMIN_CLIENT_ID']))

docs/api-usage.md

@@ -8,3 +8,15 @@ For a usage example, see [our Python demo](https://github.com/GSA/notify-python-
 
 An API key can be created at https://notifications-admin.app.cloud.gov/services/YOUR_SERVICE_ID/api/keys. However, in order to successfully send messages, you will need to receive a secret header token from the Notify team.
 
+
+## Using OpenAPI documentation
+
+### Retrieving a bearer token for use
+
+On a mac, run
+
+```
+flask command create-admin-jwt | tail -n 1 | pbcopy
+```
+
+to copy a token usable by the admin UI to your pasteboard. This token will expire in 30 seconds

docs/openapi.yml

@@ -9,6 +9,58 @@ servers:
     description: Staging API endpoint
   - url: http://localhost:6011
     description: Local development API endpoint
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+  schemas:
+    userObject:
+      type: object
+      properties:
+        auth_type:
+          type: string
+        can_use_webauthn:
+          type: string
+        current_session_id:
+          type: string
+        email_access_validated_at:
+          type: string
+        email_address:
+          type: string
+        failed_login_count:
+          type: number
+        id:
+          type: string
+        logged_in_at:
+          type: string
+        mobile_number:
+          type: string
+        name:
+          type: string
+        organisations:
+          type: array
+          items:
+            type: string
+        password_changed_at:
+          type: string
+        permissions:
+          type: object
+          properties:
+            SERVICE_ID:
+              type: array
+              items:
+                type: string
+        platform_admin:
+          type: boolean
+        services:
+          type: array
+          items:
+            type: string
+        state:
+          type: string
+          enum: ["pending", "active", "inactive"]
 paths:
   /_status?simple=1:
     get:
@@ -60,3 +112,42 @@ paths:
                     type: number
                   organisations:
                     type: number
+  /user:
+    get:
+      security:
+        - bearerAuth: []
+      description: 'Retrieve list of all users'
+      parameters: []
+      responses:
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: "#/components/schemas/userObject"
+  /user/{uuid}:
+    get:
+      security:
+        - bearerAuth: []
+      description: 'Retrieve single user details'
+      parameters:
+        - name: uuid
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    $ref: "#/components/schemas/userObject"