From cb6caf4ac16a1b17fb39d9d549f8109849778a06 Mon Sep 17 00:00:00 2001 From: Drew Short Date: Sun, 29 Jul 2018 21:42:21 -0500 Subject: [PATCH] Adding sphinxjsondomain to document json objects --- server/Pipfile | 1 + server/Pipfile.lock | 24 +- server/documentation/api/authentication.rst | 173 ++++---- server/documentation/api/user.rst | 457 +++++++++++--------- server/documentation/conf.py | 3 +- 5 files changed, 371 insertions(+), 287 deletions(-) diff --git a/server/Pipfile b/server/Pipfile index ba49ae6..1d7e34d 100644 --- a/server/Pipfile +++ b/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" diff --git a/server/Pipfile.lock b/server/Pipfile.lock index 09c1089..0cc196f 100644 --- a/server/Pipfile.lock +++ b/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", diff --git a/server/documentation/api/authentication.rst b/server/documentation/api/authentication.rst index 477c184..59586d6 100644 --- a/server/documentation/api/authentication.rst +++ b/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 - - **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 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 + + **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 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 + POST /auth/bump HTTP/1.1 + Host: example.tld + Accept: application/json + Authorization: Token - **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 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 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 - **Example response**: - - .. sourcecode:: http - - HTTP/1.1 200 OK - Vary: Accept - Content-Type: application/json - - { - "success": true - } - - :
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 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 diff --git a/server/documentation/api/user.rst b/server/documentation/api/user.rst index c60e8bc..0eea296 100644 --- a/server/documentation/api/user.rst +++ b/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 - - **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 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 + + **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 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 + GET /user/atheneum_administrator HTTP/1.1 + Host: example.tld + Accept: application/json + Authorization: Token - **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 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 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 - 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 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 + 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 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 - 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 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 + 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 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 - - **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 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 + + **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 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 + :showexample: + + Page 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 diff --git a/server/documentation/conf.py b/server/documentation/conf.py index 900cd8b..8f4802a 100644 --- a/server/documentation/conf.py +++ b/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.