warricksothr
/
Atheneum
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity
Browse Source

Adding sphinxjsondomain to document json objects

merge-requests/8/head
Drew Short 6 years ago
parent
8419ecb7e0
commit
cb6caf4ac1
5 changed files with 371 additions and 287 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  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
View File

@ -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"

24
server/Pipfile.lock
View File

@ -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",

173
server/documentation/api/authentication.rst
View File

@ -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

457
server/documentation/api/user.rst
View File

@ -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

3
server/documentation/conf.py
View File

@ -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.

Write Preview
Loading…
Cancel
Save