Merge branch 'development' into 'master'

Adding sphinxjsondomain to document json objects

See merge request warricksothr/Atheneum!8

server/Pipfile

@@ -24,6 +24,7 @@ pydocstyle = ">=2.1,<2.2"
 sphinx = ">=1.7,<1.8"
 sphinx-rtd-theme = ">=0.4,<0.5"
 sphinxcontrib-httpdomain = ">=1.7,<1.8"
+sphinx-jsondomain = "*"
 
 [requires]
 python_version = "3.6"

server/Pipfile.lock

@@ -1,7 +1,7 @@
 {
     "_meta": {
         "hash": {
-            "sha256": "2d44286a15539f26e69e12737247e8f490fa6c5e1f35a28f5c322cbd525d5eda"
+            "sha256": "9ba0840844223ce8320a900a02e33f5ea9314301a827f49f0b92a4eff7227812"
         },
         "pipfile-spec": 6,
         "requires": {
@@ -314,6 +314,13 @@
             ],
             "version": "==0.14"
         },
+        "faker": {
+            "hashes": [
+                "sha256:228970fbdd8322e92406cff256338c1cf0a330332d0172f4403863689a3c5576",
+                "sha256:310b20f3c497a777622920dca314d90f774028d49c7ee7ccfa96ca4b9d9bf429"
+            ],
+            "version": "==0.7.18"
+        },
         "idna": {
             "hashes": [
                 "sha256:156a6814fb5ac1fc6850fb002e0852d56c0c8d2531923a51032d1b70760e186e",
@@ -495,6 +502,13 @@
             "index": "pypi",
             "version": "==3.6.4"
         },
+        "python-dateutil": {
+            "hashes": [
+                "sha256:1adb80e7a782c12e52ef9a8182bebeb73f1d7e24e374397af06fb4956c8dc5c0",
+                "sha256:e27001de32f627c22380a688bcc43ce83504a7bc5da472209b4c70f02829f0b8"
+            ],
+            "version": "==2.7.3"
+        },
         "python-dotenv": {
             "hashes": [
                 "sha256:4965ed170bf51c347a89820e8050655e9c25db3837db6602e906b6d850fad85c",
@@ -539,6 +553,14 @@
             "index": "pypi",
             "version": "==1.7.6"
         },
+        "sphinx-jsondomain": {
+            "hashes": [
+                "sha256:cdc03fa28dafc383d30451d724ea293dded4619d777acfa003b2a538bbf52f85",
+                "sha256:fd4688d3026bd40c8d3aea94c0ea423d32dd9a046e6dc80fba83aaf60c87abc4"
+            ],
+            "index": "pypi",
+            "version": "==0.0.3"
+        },
         "sphinx-rtd-theme": {
             "hashes": [
                 "sha256:3b49758a64f8a1ebd8a33cb6cc9093c3935a908b716edfaa5772fd86aac27ef6",

server/documentation/api/authentication.rst

@@ -3,103 +3,126 @@ Authentication API
 
 .. http:post:: /auth/login
 
-   Authenticate with the server and receive a userToken for requests.
+    Authenticate with the server and receive a userToken for requests.
 
-   **Example request**:
+    **Example request**:
 
-   .. sourcecode:: http
+    .. sourcecode:: http
 
-      POST /auth/login HTTP/1.1
-      Host: example.tld
-      Accept: application/json
-      Authorization: Basic <Base64 Encoded Basic Auth>
-
-   **Example response**:
-
-   .. sourcecode:: http
-
-      HTTP/1.1 200 OK
-      Vary: Accept
-      Content-Type: application/json
-
-      {
-        "creationTime": "2018-07-29T11:59:29-05:00",
-        "enabled": true,
-        "token": "b94cf5c7-cddc-4610-9d4c-6b8e04088ae8",
-        "version": 0
-      }
-
-   :<header Accept: Response content type depends on :mailheader:`Accept` header
-   :<header Authorization: Encoded basic authorization
-   :>header Content-Type: Depends on :mailheader:`Accept` header of request
-   :>json datetime creationTime: Creation time for the userToken
-   :>json datetime expirationTime: Expiration time for the userToken
-   :>json boolean enabled: Whether the userToken is enabled
-   :>json string token: UserToken to use for further authentication
-   :>json int version: Version for the object
-   :statuscode 200: User successfully logged in
-   :statuscode 401: Authorization failed
+        POST /auth/login HTTP/1.1
+        Host: example.tld
+        Accept: application/json
+        Authorization: Basic <Base64 Encoded Basic Auth>
+
+    **Example response**:
+
+    .. sourcecode:: http
+
+        HTTP/1.1 200 OK
+        Vary: Accept
+        Content-Type: application/json
+
+        {
+            "creationTime": "2018-07-29T11:59:29-05:00",
+            "enabled": true,
+            "token": "b94cf5c7-cddc-4610-9d4c-6b8e04088ae8",
+            "version": 0
+        }
+
+    :<header Accept: Response content type depends on :mailheader:`Accept` header
+    :<header Authorization: Encoded basic authorization
+    :>header Content-Type: Depends on :mailheader:`Accept` header of request
+    :>json datetime creationTime: Creation time for the userToken
+    :>json datetime expirationTime: Expiration time for the userToken
+    :>json boolean enabled: Whether the userToken is enabled
+    :>json string token: UserToken to use for further authentication
+    :>json int version: Version for the object
+    :statuscode 200: User successfully logged in
+    :statuscode 401: Authorization failed
 
 .. http:post:: /auth/bump
 
-   Bump user login information.
+    Bump user login information.
 
-   **Example request**:
+    **Example request**:
 
-   .. sourcecode:: http
+    .. sourcecode:: http
 
-      POST /auth/bump HTTP/1.1
-      Host: example.tld
-      Accept: application/json
-      Authorization: Token <Base64(user:userToken)>
+        POST /auth/bump HTTP/1.1
+        Host: example.tld
+        Accept: application/json
+        Authorization: Token <Base64(user:userToken)>
 
-   **Example response**:
+    **Example response**:
 
-   .. sourcecode:: http
+    .. sourcecode:: http
 
-      HTTP/1.1 200 OK
-      Vary: Accept
-      Content-Type: application/json
+        HTTP/1.1 200 OK
+        Vary: Accept
+        Content-Type: application/json
 
-      {
-        "lastLoginTime": "2018-07-29T12:15:51-05:00"
-      }
+        {
+            "lastLoginTime": "2018-07-29T12:15:51-05:00"
+        }
 
-   :<header Accept: Response content type depends on :mailheader:`Accept` header
-   :<header Authorization: Encoded token authorization
-   :>header Content-Type: Depends on :mailheader:`Accept` header of request
-   :>json datetime lastLoginTime: Updated lastLoginTime for the user
-   :statuscode 200: User last_login_time successfully bumped
-   :statuscode 401: Authorization failed
+    :<header Accept: Response content type depends on :mailheader:`Accept` header
+    :<header Authorization: Encoded token authorization
+    :>header Content-Type: Depends on :mailheader:`Accept` header of request
+    :>json datetime lastLoginTime: Updated lastLoginTime for the user
+    :statuscode 200: User last_login_time successfully bumped
+    :statuscode 401: Authorization failed
 
 .. http:post:: /auth/logout
 
-   Logout a user and remove the provided userToken from valid tokens.
+    Logout a user and remove the provided userToken from valid tokens.
 
-   **Example request**:
+    **Example request**:
 
-   .. sourcecode:: http
+    .. sourcecode:: http
 
       POST /auth/logout HTTP/1.1
       Host: example.tld
       Accept: application/json
       Authorization: Token <Base64(user:userToken)>
 
-   **Example response**:
-
-   .. sourcecode:: http
-
-      HTTP/1.1 200 OK
-      Vary: Accept
-      Content-Type: application/json
-
-      {
-        "success": true
-      }
-
-   :<header Accept: Response content type depends on :mailheader:`Accept` header
-   :<header Authorization: Rncoded token authorization
-   :>header Content-Type: Depends on :mailheader:`Accept` header of request
-   :>json boolean success: Whether the logout was successful
-   :statuscode 200: User successfully logged out
-   :statuscode 401: Authorization failed
+    **Example response**:
+
+    .. sourcecode:: http
+
+        HTTP/1.1 200 OK
+        Vary: Accept
+        Content-Type: application/json
+
+        {
+            "success": true
+        }
+
+    :<header Accept: Response content type depends on :mailheader:`Accept` header
+    :<header Authorization: Rncoded token authorization
+    :>header Content-Type: Depends on :mailheader:`Accept` header of request
+    :>json boolean success: Whether the logout was successful
+    :statuscode 200: User successfully logged out
+    :statuscode 401: Authorization failed
+
+Authentication Object Models
+============================
+
+.. json:object:: UserToken
+   :showexample:
+
+   UserToken definition
+
+   :property token: The token value, used for authentication
+   :proptype token: string
+   :property note: Additional information about the token
+   :proptype note: string
+   :property enabled: Determine if a token will be accepted
+   :proptype enabled: boolean
+   :property expirationTime: The time that the token becomes invalid, regardless of enabled state
+   :proptype expirationTime: iso8601
+   :property creationTime: The time that the token was created
+   :proptype creationTime: iso8601
+   :property lastUsageTime: The time that the token was last used
+   :proptype lastUsageTime: iso8601
+   :property version: An identifier for the token version
+   :proptype version: integer

server/documentation/api/user.rst

@@ -3,234 +3,271 @@ User API
 
 .. http:get:: /user
 
-   Get a page of users.
-
-   **Example request**
-
-   .. sourcecode:: http
-
-      GET /user HTTP/1.1
-      Host: example.tld
-      Accept: application/json
-      Authorization: Token <Base64(user:userToken)>
-
-   **Example response**:
-
-   .. sourcecode:: http
-
-      HTTP/1.1 200 OK
-      Vary: Accept
-      Content-Type: application/json
-
-      {
-        "page": 1,
-        "count": 1,
-        "totalCount": 1,
-        "lastPage": 1,
-        "items" :[{
-          "creationTime": "2018-07-29T11:58:17-05:00",
-          "lastLoginTime": "2018-07-29T12:43:27-05:00",
-          "name": "atheneum_administrator",
-          "role": "ADMIN",
-          "version": 0
-        }]
-      }
-
-   :query int page: User page to retrieve
-   :query int perPage: Number of records to retrieve per page (max 100)
-   :<header Accept: Response content type depends on :mailheader:`Accept` header
-   :<header Authorization: The encoded basic authorization
-   :>header Content-Type: Depends on :mailheader:`Accept` header of request
-   :>json int page: Page retrieved
-   :>json int count: Number of items returned
-   :>json int totalCount: Total number of items available
-   :>json int lastPage: Last page that can be requested before 404
-   :>json int items: List of Users
-   :statuscode 200: Successfully retrieved the user
-   :statuscode 400: Invalid page or perPage values
-   :statuscode 401: Authorization failed
-   :statuscode 404: User page doesn't exist
+    Get a page of users.
+
+    **Example request**
+
+    .. sourcecode:: http
+
+        GET /user HTTP/1.1
+        Host: example.tld
+        Accept: application/json
+        Authorization: Token <Base64(user:userToken)>
+
+    **Example response**:
+
+    .. sourcecode:: http
+
+        HTTP/1.1 200 OK
+        Vary: Accept
+        Content-Type: application/json
+
+        {
+            "page": 1,
+            "count": 1,
+            "totalCount": 1,
+            "lastPage": 1,
+            "items": [
+                {
+                    "creationTime": "2018-07-29T11:58:17-05:00",
+                    "lastLoginTime": "2018-07-29T12:43:27-05:00",
+                    "name": "atheneum_administrator",
+                    "role": "ADMIN",
+                    "version": 0
+                }
+            ]
+        }
+
+    :query int page: User page to retrieve
+    :query int perPage: Number of records to retrieve per page (max 100)
+    :<header Accept: Response content type depends on :mailheader:`Accept` header
+    :<header Authorization: The encoded basic authorization
+    :>header Content-Type: Depends on :mailheader:`Accept` header of request
+    :>json int page: Page retrieved
+    :>json int count: Number of items returned
+    :>json int totalCount: Total number of items available
+    :>json int lastPage: Last page that can be requested before 404
+    :>json int items: List of Users
+    :statuscode 200: Successfully retrieved the user
+    :statuscode 400: Invalid page or perPage values
+    :statuscode 401: Authorization failed
+    :statuscode 404: User page doesn't exist
 
 
 .. http:get:: /user/(str:user_name)
 
-   Find a user by name.
+    Find a user by name.
 
-   **Example request**:
+    **Example request**:
 
-   .. sourcecode:: http
+    .. sourcecode:: http
 
-      GET /user/atheneum_administrator HTTP/1.1
-      Host: example.tld
-      Accept: application/json
-      Authorization: Token <Base64(user:userToken)>
+        GET /user/atheneum_administrator HTTP/1.1
+        Host: example.tld
+        Accept: application/json
+        Authorization: Token <Base64(user:userToken)>
 
-   **Example response**:
+    **Example response**:
 
-   .. sourcecode:: http
+    .. sourcecode:: http
 
-      HTTP/1.1 200 OK
-      Vary: Accept
-      Content-Type: application/json
+        HTTP/1.1 200 OK
+        Vary: Accept
+        Content-Type: application/json
 
-      {
-        "creationTime": "2018-07-29T11:58:17-05:00",
-        "lastLoginTime": "2018-07-29T12:43:27-05:00",
-        "name": "atheneum_administrator",
-        "role": "ADMIN",
-        "version": 0
-      }
+        {
+            "creationTime": "2018-07-29T11:58:17-05:00",
+            "lastLoginTime": "2018-07-29T12:43:27-05:00",
+            "name": "atheneum_administrator",
+            "role": "ADMIN",
+            "version": 0
+        }
 
-   :param string user_name: Name of the user to retrieve information about
-   :<header Accept: Response content type depends on :mailheader:`Accept` header
-   :<header Authorization: The encoded basic authorization
-   :>header Content-Type: Depends on :mailheader:`Accept` header of request
-   :>json datetime creationTime: Creation time for the user
-   :>json datetime lastLoginTime: When the user last logged in, or was last bumped
-   :>json string name: The user name
-   :>json string role: The role assigned to the user
-   :>json int version: Version information
-   :statuscode 200: Successfully retrieved the user
-   :statuscode 401: Authorization failed
-   :statuscode 404: User doesn't exist
+    :param string user_name: Name of the user to retrieve information about
+    :<header Accept: Response content type depends on :mailheader:`Accept` header
+    :<header Authorization: The encoded basic authorization
+    :>header Content-Type: Depends on :mailheader:`Accept` header of request
+    :>json datetime creationTime: Creation time for the user
+    :>json datetime lastLoginTime: When the user last logged in, or was last bumped
+    :>json string name: The user name
+    :>json string role: The role assigned to the user
+    :>json int version: Version information
+    :statuscode 200: Successfully retrieved the user
+    :statuscode 401: Authorization failed
+    :statuscode 404: User doesn't exist
 
 .. http:patch:: /user/(str:user_name)
 
-   Patch a user.
-
-   **Example request**:
-
-   .. sourcecode:: http
-
-      PATCH /user/atheneum_administrator HTTP/1.1
-      Host: example.tld
-      Accept: application/json
-      Authorization: Token <Base64(user:userToken)>
-      Content-Type: application/json
-
-      {
-        "lastLoginTime": "2019-07-29T12:43:27-05:00",
-        "version": 0
-      }
-
-   **Example response**:
-
-   .. sourcecode:: http
-
-      HTTP/1.1 200 OK
-      Vary: Accept
-      Content-Type: application/json
-
-      {
-        "creationTime": "2018-07-29T11:58:17-05:00",
-        "lastLoginTime": "2019-07-29T12:43:27-05:00",
-        "name": "atheneum_administrator",
-        "role": "ADMIN",
-        "version": 1
-      }
-
-   :param string user_name: Name of the user to update
-   :<header Accept: Response content type depends on :mailheader:`Accept` header
-   :<header Authorization: Encoded token authorization
-   :<header Content-Type: application/json
-   :<json datetime createDateTime: Update createDateTime (Administrator Only)
-   :<json datetime lastLoginTime: Update lastLoginTime
-   :<json string name: Update user name (Administrator Only)
-   :<json string role: Update user role (Must be less than or equal to the role authenticating the action)
-   :<json int version: Must match the latest version of the user
-   :>header Content-Type: Depends on :mailheader:`Accept` header of request
-   :>json datetime creationTime: Creation time for the user
-   :>json datetime lastLoginTime: When the user last logged in, or was last bumped
-   :>json string name: The user name
-   :>json string role: The role assigned to the user
-   :>json int version: Version information
-   :statuscode 200: Successfully patched the user
-   :statuscode 400: An issue in the payload was discovered
-   :statuscode 401: Authorization failed
-   :statuscode 404: User doesn't exist
+    Patch a user.
+
+    **Example request**:
+
+    .. sourcecode:: http
+
+        PATCH /user/atheneum_administrator HTTP/1.1
+        Host: example.tld
+        Accept: application/json
+        Authorization: Token <Base64(user:userToken)>
+        Content-Type: application/json
+
+        {
+            "lastLoginTime": "2019-07-29T12:43:27-05:00",
+            "version": 0
+        }
+
+    **Example response**:
+
+    .. sourcecode:: http
+
+        HTTP/1.1 200 OK
+        Vary: Accept
+        Content-Type: application/json
+
+        {
+            "creationTime": "2018-07-29T11:58:17-05:00",
+            "lastLoginTime": "2019-07-29T12:43:27-05:00",
+            "name": "atheneum_administrator",
+            "role": "ADMIN",
+            "version": 1
+        }
+
+    :param string user_name: Name of the user to update
+    :<header Accept: Response content type depends on :mailheader:`Accept` header
+    :<header Authorization: Encoded token authorization
+    :<header Content-Type: application/json
+    :<json datetime createDateTime: Update createDateTime (Administrator Only)
+    :<json datetime lastLoginTime: Update lastLoginTime
+    :<json string name: Update user name (Administrator Only)
+    :<json string role: Update user role (Must be less than or equal to the role authenticating the action)
+    :<json int version: Must match the latest version of the user
+    :>header Content-Type: Depends on :mailheader:`Accept` header of request
+    :>json datetime creationTime: Creation time for the user
+    :>json datetime lastLoginTime: When the user last logged in, or was last bumped
+    :>json string name: The user name
+    :>json string role: The role assigned to the user
+    :>json int version: Version information
+    :statuscode 200: Successfully patched the user
+    :statuscode 400: An issue in the payload was discovered
+    :statuscode 401: Authorization failed
+    :statuscode 404: User doesn't exist
 
 .. http:post:: /user
 
-   Register a new user with the service.
-
-   **Example request**:
-
-   .. sourcecode:: http
-
-      POST /user HTTP/1.1
-      Host: example.tld
-      Accept: application/json
-      Authorization: Token <Base64(user:userToken)>
-      Content-Type: application/json
-
-      {
-        "name": "test_user",
-        "password": "JvZ9bm79",
-        "role": "USER"
-      }
-
-   **Example response**:
-
-   .. sourcecode:: http
-
-      HTTP/1.1 200 OK
-      Vary: Accept
-      Content-Type: application/json
-
-      {
-        "creationTime": "2018-07-29T14:16:48-05:00",
-        "name": "test_user",
-        "role": "USER",
-        "version": 0
-      }
-
-   :<header Accept: Response content type depends on :mailheader:`Accept` header
-   :<header Authorization: Encoded token authorization
-   :<header Content-Type: application/json
-   :<json string name: Name of the user
-   :<json string password: Password to use
-   :<json string role: Role to assign to the user (Must be less than or equal to the role of the authenticating user)
-   :>header Content-Type: Depends on :mailheader:`Accept` header of request
-   :>json datetime creationTime: Datetime the user was created
-   :>json string name: Name of the created user
-   :>json string role: Role of the created user
-   :>json int version: Version number of the created user
-   :statuscode 200: Successfully registered the user
-   :statuscode 400: An issue in the payload was discovered
-   :statuscode 401: Authorization failed
+    Register a new user with the service.
+
+    **Example request**:
+
+    .. sourcecode:: http
+
+        POST /user HTTP/1.1
+        Host: example.tld
+        Accept: application/json
+        Authorization: Token <Base64(user:userToken)>
+        Content-Type: application/json
+
+        {
+            "name": "test_user",
+            "password": "JvZ9bm79",
+            "role": "USER"
+        }
+
+    **Example response**:
+
+    .. sourcecode:: http
+
+        HTTP/1.1 200 OK
+        Vary: Accept
+        Content-Type: application/json
+
+        {
+            "creationTime": "2018-07-29T14:16:48-05:00",
+            "name": "test_user",
+            "role": "USER",
+            "version": 0
+        }
+
+    :<header Accept: Response content type depends on :mailheader:`Accept` header
+    :<header Authorization: Encoded token authorization
+    :<header Content-Type: application/json
+    :<json string name: Name of the user
+    :<json string password: Password to use
+    :<json string role: Role to assign to the user (Must be less than or equal to the role of the authenticating user)
+    :>header Content-Type: Depends on :mailheader:`Accept` header of request
+    :>json datetime creationTime: Datetime the user was created
+    :>json string name: Name of the created user
+    :>json string role: Role of the created user
+    :>json int version: Version number of the created user
+    :statuscode 200: Successfully registered the user
+    :statuscode 400: An issue in the payload was discovered
+    :statuscode 401: Authorization failed
 
 .. http:delete:: /user/(str:user_name)
 
-   Register a new user with the service.
-
-   **Example request**:
-
-   .. sourcecode:: http
-
-      DELETE /user/test_user HTTP/1.1
-      Host: example.tld
-      Accept: application/json
-      Authorization: Token <Base64(user:userToken)>
-
-   **Example response**:
-
-   .. sourcecode:: http
-
-      HTTP/1.1 200 OK
-      Vary: Accept
-      Content-Type: application/json
-
-      {
-        "message": "Successfully Deleted",
-        "success": true
-      }
-
-   :param string user_name: Name of the user to delete
-   :<header Accept: Response content type depends on :mailheader:`Accept` header
-   :<header Authorization: Encoded token authorization
-   :>header Content-Type: Depends on :mailheader:`Accept` header of request
-   :>json string message: Success or failure message
-   :>json boolean success: Action status indicator
-   :statuscode 200: Successfully deleted the user
-   :statuscode 401: Authorization failed
-   :statuscode 404: User doesn't exist
+    Register a new user with the service.
+
+    **Example request**:
+
+    .. sourcecode:: http
+
+        DELETE /user/test_user HTTP/1.1
+        Host: example.tld
+        Accept: application/json
+        Authorization: Token <Base64(user:userToken)>
+
+    **Example response**:
+
+    .. sourcecode:: http
+
+        HTTP/1.1 200 OK
+        Vary: Accept
+        Content-Type: application/json
+
+        {
+            "message": "Successfully Deleted",
+            "success": true
+        }
+
+    :param string user_name: Name of the user to delete
+    :<header Accept: Response content type depends on :mailheader:`Accept` header
+    :<header Authorization: Encoded token authorization
+    :>header Content-Type: Depends on :mailheader:`Accept` header of request
+    :>json string message: Success or failure message
+    :>json boolean success: Action status indicator
+    :statuscode 200: Successfully deleted the user
+    :statuscode 401: Authorization failed
+    :statuscode 404: User doesn't exist
+
+User Object Models
+==================
+
+.. json:object:: Page<User>
+    :showexample:
+
+    Page<User> definition
+
+    :property page: The page returned
+    :proptype page: integer
+    :property count: The number of items on this page
+    :proptype count: integer
+    :property totalCount: The total number of items available
+    :proptype totalCount: integer
+    :property lastPage: The last page that is accessible before 404
+    :proptype lastPage: integer
+    :property items: The list of items on the page
+    :proptype items: :json:list: 'User'
+
+.. json:object:: User
+    :showexample:
+
+    User definition
+
+    :property name: The unique name of the user
+    :proptype name: string
+    :property creationTime: The time that the user was created
+    :proptype creationTime: iso8601
+    :property lastLoginTime: The time that the user last logged in
+    :proptype lastLoginTime: iso8601
+    :property version: An identifier for the user version
+    :proptype version: integer
+    :property role: The assigned role for the user
+    :proptype role: string

server/documentation/conf.py

@@ -39,7 +39,8 @@ release = '2018.8.1'
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'sphinxcontrib.httpdomain'
+    'sphinxcontrib.httpdomain',
+    'sphinxjsondomain'
 ]
 
 # Add any paths that contain templates here, relative to this directory.