diff --git a/api/swagger.yaml b/api/swagger.yaml index 5bcda30..6bd5f82 100644 --- a/api/swagger.yaml +++ b/api/swagger.yaml @@ -12,7 +12,7 @@ paths: post: tags: - Auth Endpoints - summary: Attemps to log in a user with credentials, and returns an access token. + summary: Attempts to log in a user with credentials, and returns an access token. requestBody: $ref: '#/components/requestBodies/AuthCredentials' responses: @@ -25,7 +25,7 @@ paths: 400: $ref: '#/components/responses/MalformedBody' 401: - $ref: '#/components/responses/InvalidCredentials' + $ref: '#/components/responses/InvalidCredentials' 500: $ref: '#/components/responses/ServerError' /auth/logout: @@ -34,10 +34,10 @@ paths: - Auth Endpoints summary: Logs out a user, making their access token invalid. security: - - token: [] + - token: [ ] responses: 200: - description: You have successfully logged out, and your token is now invalid. + description: You have successfully logged out, and the token used to authenticate the request is now revoked/invalid. content: application/json: schema: @@ -69,8 +69,8 @@ paths: type: object 400: $ref: '#/components/responses/MalformedBody' - 401: - $ref: '#/components/responses/InvalidToken' + 422: + $ref: '#/components/responses/Unprocessable' 500: $ref: '#/components/responses/ServerError' @@ -78,7 +78,7 @@ paths: get: tags: - User Endpoints - summary: Get the information for a user. + summary: Get information for a user. parameters: - name: username required: true @@ -108,7 +108,7 @@ paths: - $ref: '#/components/parameters/BeforeParam' - $ref: '#/components/parameters/LimitParam' - $ref: '#/components/parameters/CountParam' - summary: Get the list of posts a user has created/submitted. + summary: Get a list of posts a user has created/submitted. responses: 200: description: A list of posts filtered and formatted. @@ -140,7 +140,7 @@ paths: - $ref: '#/components/parameters/BeforeParam' - $ref: '#/components/parameters/LimitParam' - $ref: '#/components/parameters/CountParam' - summary: Get the list of comments a user has submitted. + summary: Get a list of paginated comments a user has submitted. responses: 200: description: A list of comments filtered and formatted. @@ -159,7 +159,9 @@ paths: /posts: get: - summary: Get a list of posts + tags: + - Post Endpoints + summary: Get a list of paginated posts description: The items retrieved will always show newest first. parameters: - name: filter @@ -192,7 +194,7 @@ paths: tags: - Post Endpoints security: - - token: [] + - token: [ ] requestBody: description: Submit a new post with this endpoint. required: true @@ -228,6 +230,36 @@ paths: $ref: '#/components/responses/Unprocessable' 500: $ref: '#/components/responses/ServerError' + + /post/{id}: + get: + tags: + - Post Endpoints + parameters: + - name: id + in: path + required: true + description: The post ID to retrieve information about + schema: + type: string + responses: + 200: + description: Information regarding a post + content: + application/json: + schema: + type: object + allOf: + - $ref: '#/components/schemas/Post' + - type: object + required: + - comments + properties: + comments: + type: array + items: + $ref: '#/components/schemas/Comment' + components: parameters: AfterParam: @@ -249,7 +281,7 @@ components: LimitParam: name: limit in: query - description: Maximimum number of items to return + description: Maximum number of items to return schema: type: integer maximum: 100 @@ -319,7 +351,7 @@ components: reason: Varies code: 422 ServerError: - description: The server could not complete a request due to an unknown error. More information may be available in the description. + description: The server could not complete a request due to an unknown error. More information may be available in the 'reason' parameter. content: application/json: schema: @@ -336,13 +368,13 @@ components: - password properties: username: - description: A Unique uusername to identify a user around the website. + description: A unique username to identify a user around the website. type: string minLength: 3 maxLength: 16 pattern: "[a-zA-Z0-9 ]{3,16}" email: - description: A Unique email used for communication/further identification. + description: A unique email used for communication/further identification. type: string format: email password: @@ -357,6 +389,20 @@ components: - username - points - date_created + properties: + id: + type: string + description: The unique ID of the user + username: + type: string + description: The username of the user + points: + type: number + description: The number of points (sum of upvotes and downvotes) of a user + date_created: + type: string + format: 'date-time' + description: When the user's account was created Token: required: - token @@ -448,4 +494,4 @@ components: securitySchemes: token: type: http - scheme: bearer \ No newline at end of file + scheme: bearer