Browse Source

Adding sphinxjsondomain to document json objects

merge-requests/8/head
Drew Short 6 years ago
parent
commit
cb6caf4ac1
  1. 1
      server/Pipfile
  2. 24
      server/Pipfile.lock
  3. 173
      server/documentation/api/authentication.rst
  4. 457
      server/documentation/api/user.rst
  5. 3
      server/documentation/conf.py

1
server/Pipfile

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

24
server/Pipfile.lock

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

173
server/documentation/api/authentication.rst

@ -3,103 +3,126 @@ Authentication API
.. http:post:: /auth/login .. 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 .. 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 .. 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 POST /auth/logout HTTP/1.1
Host: example.tld Host: example.tld
Accept: application/json Accept: application/json
Authorization: Token <Base64(user:userToken)> 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

457
server/documentation/api/user.rst

@ -3,234 +3,271 @@ User API
.. http:get:: /user .. 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) .. 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) .. 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 .. 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) .. 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

3
server/documentation/conf.py

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

Loading…
Cancel
Save