swagger: add /post/{id} endpoint, fix semantic/grammatical errors

master
ALI Hamza 2020-09-10 17:48:20 +07:00
parent 407f9e2630
commit a071edec1b
Signed by: hamza
GPG Key ID: 22473A32291F8CB6
1 changed files with 62 additions and 16 deletions

@ -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:
@ -37,7 +37,7 @@ paths:
- 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
@ -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