641 lines
23 KiB
YAML
641 lines
23 KiB
YAML
openapi: 3.0.0
|
|
servers:
|
|
- description: SwaggerHub API Auto Mocking
|
|
url: 'https://virtserver.swaggerhub.com/C4theBomb/know-it-all/1.0.0'
|
|
- description: Localhost Server
|
|
url: 'http://localhost:3000/api'
|
|
info:
|
|
version: 1.0.0
|
|
title: KnowItAll API
|
|
description: >-
|
|
This API will interact with the KnowItAll frontend to deliver data securely
|
|
between the client and the database. Authorization is done through the
|
|
`authorization` header and has two scopes, `bearer` and `basic`.
|
|
paths:
|
|
/auth/register:
|
|
post:
|
|
summary: Register a new user
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
firstName:
|
|
type: string
|
|
lastName:
|
|
type: string
|
|
email:
|
|
type: string
|
|
format: email
|
|
password:
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: OK
|
|
'400':
|
|
$ref: '#/components/responses/BadRequest'
|
|
'500':
|
|
$ref: '#/components/responses/ServerError'
|
|
tags:
|
|
- users
|
|
/auth/login:
|
|
post:
|
|
summary: Login a user and receive an authentication token
|
|
security:
|
|
- BasicAuth: []
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
remember:
|
|
type: boolean
|
|
enum:
|
|
- true
|
|
- false
|
|
responses:
|
|
'200':
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
user:
|
|
$ref: '#/components/schemas/User'
|
|
token:
|
|
type: string
|
|
'400':
|
|
$ref: '#/components/responses/BadRequest'
|
|
'403':
|
|
$ref: '#/components/responses/Forbidden'
|
|
'404':
|
|
$ref: '#/components/responses/NotFound'
|
|
'500':
|
|
$ref: '#/components/responses/ServerError'
|
|
tags:
|
|
- users
|
|
/auth/logout:
|
|
delete:
|
|
summary: Logout a user
|
|
security:
|
|
- BearerAuth: []
|
|
responses:
|
|
'200':
|
|
description: OK
|
|
'400':
|
|
$ref: '#/components/responses/BadRequest'
|
|
'401':
|
|
$ref: '#/components/responses/Unauthenticated'
|
|
'500':
|
|
$ref: '#/components/responses/ServerError'
|
|
tags:
|
|
- users
|
|
/auth/remember:
|
|
get:
|
|
summary: Retrieve data of the authenticated user
|
|
security:
|
|
- BearerAuth: []
|
|
responses:
|
|
'200':
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
user:
|
|
$ref: '#/components/schemas/User'
|
|
'400':
|
|
$ref: '#/components/responses/BadRequest'
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'500':
|
|
$ref: '#/components/responses/ServerError'
|
|
tags:
|
|
- users
|
|
/auth/update:
|
|
post:
|
|
summary: Update user details
|
|
security:
|
|
- BearerAuth: []
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
firstName:
|
|
type: string
|
|
lastName:
|
|
type: string
|
|
email:
|
|
type: string
|
|
format: email
|
|
responses:
|
|
'200':
|
|
description: OK
|
|
'400':
|
|
$ref: '#/components/responses/BadRequest'
|
|
'401':
|
|
$ref: '#/components/responses/Unauthenticated'
|
|
'409':
|
|
$ref: '#/components/responses/DuplicateName'
|
|
'500':
|
|
$ref: '#/components/responses/ServerError'
|
|
tags:
|
|
- users
|
|
/auth/update/audio:
|
|
post:
|
|
summary: Upload an audio file for the user
|
|
security:
|
|
- BearerAuth: []
|
|
responses:
|
|
'200':
|
|
description: OK
|
|
'400':
|
|
$ref: '#/components/responses/BadRequest'
|
|
'401':
|
|
$ref: '#/components/responses/Unauthenticated'
|
|
'500':
|
|
$ref: '#/components/responses/ServerError'
|
|
tags:
|
|
- users
|
|
/auth/reset:
|
|
post:
|
|
summary: Get a link for the user to reset their password
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
email:
|
|
type: string
|
|
format: email
|
|
description: Username of the user that need to reset their password.
|
|
responses:
|
|
'200':
|
|
description: OK
|
|
'400':
|
|
$ref: '#/components/responses/BadRequest'
|
|
'404':
|
|
$ref: '#/components/responses/NotFound'
|
|
'500':
|
|
$ref: '#/components/responses/ServerError'
|
|
tags:
|
|
- users
|
|
/auth/reset/{id}:
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
example: ce628f8c-000d-49dc-81b7-3ccd48f2ed6f
|
|
description: >-
|
|
This should be the ID of the request that was created in the request
|
|
page.
|
|
post:
|
|
summary: Reset the user's password
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
password:
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: OK
|
|
'400':
|
|
$ref: '#/components/responses/BadRequest'
|
|
'500':
|
|
$ref: '#/components/responses/ServerError'
|
|
tags:
|
|
- users
|
|
/auth/{id}:
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
example: 951b3d6c-2f13-46df-b91e-e5adb3de08d0
|
|
description: This should be the ID of the desired user.
|
|
get:
|
|
summary: Get the information of a known user
|
|
security:
|
|
- BearerAuth: []
|
|
responses:
|
|
'200':
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
user:
|
|
$ref: '#/components/schemas/User'
|
|
'400':
|
|
$ref: '#/components/responses/BadRequest'
|
|
'401':
|
|
$ref: '#/components/responses/Unauthenticated'
|
|
'403':
|
|
$ref: '#/components/responses/Forbidden'
|
|
'404':
|
|
$ref: '#/components/responses/NotFound'
|
|
'500':
|
|
$ref: '#/components/responses/ServerError'
|
|
tags:
|
|
- users
|
|
/auth/orgs:
|
|
get:
|
|
summary: Get all of the organization that the logged in user owns
|
|
security:
|
|
- BearerAuth: []
|
|
responses:
|
|
'200':
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
orgs:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/Organization'
|
|
tags:
|
|
- users
|
|
/auth/orgs/member:
|
|
get:
|
|
summary: Get all of the organizations that a logged in user is a part of
|
|
security:
|
|
- BearerAuth: []
|
|
responses:
|
|
'200':
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
orgs:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/Organization'
|
|
'400':
|
|
$ref: '#/components/responses/BadRequest'
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'500':
|
|
$ref: '#/components/responses/ServerError'
|
|
tags:
|
|
- users
|
|
/org:
|
|
post:
|
|
summary: Create a new organization
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
orgName:
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
org:
|
|
$ref: '#/components/schemas/Organization'
|
|
'400':
|
|
$ref: '#/components/responses/BadRequest'
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'500':
|
|
$ref: '#/components/responses/ServerError'
|
|
tags:
|
|
- organizations
|
|
/org/{id}:
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
example: 951b3d6c-2f13-46df-b91e-e5adb3de08d0
|
|
description: This should be the ID of the desired organization.
|
|
get:
|
|
summary: Get an organization
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
username:
|
|
type: string
|
|
email:
|
|
type: string
|
|
format: email
|
|
password:
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
org:
|
|
$ref: '#/components/schemas/Organization'
|
|
memberCount:
|
|
type: integer
|
|
owner:
|
|
type: boolean
|
|
'400':
|
|
$ref: '#/components/responses/BadRequest'
|
|
'401':
|
|
$ref: '#/components/responses/Unauthenticated'
|
|
'403':
|
|
$ref: '#/components/responses/Forbidden'
|
|
'404':
|
|
$ref: '#/components/responses/NotFound'
|
|
'500':
|
|
$ref: '#/components/responses/ServerError'
|
|
tags:
|
|
- organizations
|
|
patch:
|
|
summary: Modify an organization
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: OK
|
|
'400':
|
|
$ref: '#/components/responses/BadRequest'
|
|
'401':
|
|
$ref: '#/components/responses/Unauthenticated'
|
|
'404':
|
|
$ref: '#/components/responses/NotFound'
|
|
'500':
|
|
$ref: '#/components/responses/ServerError'
|
|
tags:
|
|
- organizations
|
|
delete:
|
|
summary: Delete an organization
|
|
responses:
|
|
'200':
|
|
description: OK
|
|
'400':
|
|
$ref: '#/components/responses/BadRequest'
|
|
'401':
|
|
$ref: '#/components/responses/Unauthenticated'
|
|
'403':
|
|
$ref: '#/components/responses/Forbidden'
|
|
'404':
|
|
$ref: '#/components/responses/NotFound'
|
|
'500':
|
|
$ref: '#/components/responses/ServerError'
|
|
tags:
|
|
- organizations
|
|
/org/{id}/add:
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
example: 951b3d6c-2f13-46df-b91e-e5adb3de08d0
|
|
description: This should be the ID of the desired organization.
|
|
post:
|
|
summary: Add a new user to organization
|
|
responses:
|
|
'200':
|
|
description: OK
|
|
'400':
|
|
$ref: '#/components/responses/BadRequest'
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'404':
|
|
$ref: '#/components/responses/NotFound'
|
|
'500':
|
|
$ref: '#/components/responses/ServerError'
|
|
tags:
|
|
- organizations
|
|
/org/{id}/remove:
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
example: 951b3d6c-2f13-46df-b91e-e5adb3de08d0
|
|
description: This should be the ID of the desired organization.
|
|
post:
|
|
summary: Register a new user
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
doomedUsers:
|
|
type: array
|
|
items:
|
|
type: string
|
|
example: 5f0dda65-cac8-4e61-a962-ce72ea642f1d
|
|
responses:
|
|
'200':
|
|
description: OK
|
|
'400':
|
|
$ref: '#/components/responses/BadRequest'
|
|
'401':
|
|
$ref: '#/components/responses/Unauthenticated'
|
|
'403':
|
|
$ref: '#/components/responses/Forbidden'
|
|
'404':
|
|
$ref: '#/components/responses/NotFound'
|
|
'500':
|
|
$ref: '#/components/responses/ServerError'
|
|
tags:
|
|
- organizations
|
|
components:
|
|
securitySchemes:
|
|
BasicAuth:
|
|
type: http
|
|
scheme: basic
|
|
description: >-
|
|
This is the username and password authentication method used for the
|
|
login route. The authorization header should be equal to `basic {base64
|
|
encoded username:password}` encoded into base64. The base64 encoding can
|
|
be found by running `btoa(username:password)`.
|
|
BearerAuth:
|
|
type: http
|
|
scheme: bearer
|
|
bearerFormat: jwt
|
|
description: >-
|
|
This is the JWT token authentication method used for other routes
|
|
requiring user privileges. The authorization header should be equal to
|
|
`bearer {JWT}`. The token is returned in the token property of the
|
|
`/users/login` response.
|
|
schemas:
|
|
User:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
format: uuidv4
|
|
example: 11bf5b37-e0b8-42e0-8dcf-dc8c4aefc000
|
|
firstName:
|
|
type: string
|
|
example: Edward
|
|
lastName:
|
|
type: string
|
|
example: Scissorhands
|
|
email:
|
|
type: string
|
|
format: email
|
|
pronouns:
|
|
type: string
|
|
example: he/him
|
|
createdAt:
|
|
type: string
|
|
format: date-time
|
|
updatedAt:
|
|
type: string
|
|
format: date-time
|
|
Organization:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
format: uuidv4
|
|
example: 11bf5b37-e0b8-42e0-8dcf-dc8c4aefc000
|
|
name:
|
|
type: string
|
|
example: The Rusty Pumpkin
|
|
createdAt:
|
|
type: string
|
|
format: date-time
|
|
updatedAt:
|
|
type: string
|
|
format: date-time
|
|
responses:
|
|
ServerError:
|
|
description: Server Error
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
error:
|
|
type: string
|
|
example: Oops! Something went wrong. Please try again later.
|
|
BadRequest:
|
|
description: Bad request
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
error:
|
|
type: string
|
|
example: Your request is missing information.
|
|
Unauthenticated:
|
|
description: Bad request
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
error:
|
|
type: string
|
|
example: You are unauthenticated, please log in and try again.
|
|
Forbidden:
|
|
description: User not allowed
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
error:
|
|
type: string
|
|
example: You are not authorized to do that.
|
|
NotFound:
|
|
description: Resource not found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
error:
|
|
type: string
|
|
example: That resource was not found. Please try again.
|
|
UserNotFound:
|
|
description: User not found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
error:
|
|
type: string
|
|
example: >-
|
|
A user with that email does not exist. Create an account to
|
|
get started.
|
|
DuplicateName:
|
|
description: User not found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
error:
|
|
type: string
|
|
example: >-
|
|
Something already exists with that name. Please try again with
|
|
a different name.
|
|
parameters:
|
|
userID:
|
|
name: userID
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
format: uuidv4
|
|
example: 254c574b-38c3-4a80-bd9e-a11bb0b58e35
|
|
description: This should be the object id of the desired user.
|
|
orgID:
|
|
name: orgID
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
format: uuidv4
|
|
example: 9a5fd884-fba0-4ac1-b417-fcbd382bd456
|
|
description: This should be the object id of the desired organization.
|