186 lines
5.3 KiB
YAML
186 lines
5.3 KiB
YAML
openapi: 3.0.3
|
|
info:
|
|
title: Project Ham API Specification
|
|
version: 0.0.1
|
|
contact:
|
|
name: Project Maintainer
|
|
email: me@hamzantal.pw
|
|
license:
|
|
name: MIT
|
|
paths:
|
|
/auth/login:
|
|
post:
|
|
tags:
|
|
- Auth Endpoints
|
|
summary: Attemps to log in a user with credentials, and returns an access token.
|
|
requestBody:
|
|
$ref: '#/components/requestBodies/AuthCredentials'
|
|
responses:
|
|
200:
|
|
description: You have been successfully logged in, and you can use the token to interact with the web server.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Token'
|
|
400:
|
|
$ref: '#/components/responses/MalformedBody'
|
|
401:
|
|
$ref: '#/components/responses/InvalidCredentials'
|
|
500:
|
|
$ref: '#/components/responses/ServerError'
|
|
/auth/logout:
|
|
post:
|
|
tags:
|
|
- Auth Endpoints
|
|
summary: Logs out a user, making their access token invalid.
|
|
requestBody:
|
|
$ref: '#/components/requestBodies/TokenRequest'
|
|
responses:
|
|
200:
|
|
description: You have successfully logged out, and your token is now invalid.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
400:
|
|
$ref: '#/components/responses/MalformedBody'
|
|
401:
|
|
$ref: '#/components/responses/InvalidToken'
|
|
500:
|
|
$ref: '#/components/responses/ServerError'
|
|
/auth/register:
|
|
post:
|
|
tags:
|
|
- Auth Endpoints
|
|
summary: Creates a new user account that can be used to participate with the website.
|
|
requestBody:
|
|
description: The information for the new user.
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/RegisteredUser'
|
|
responses:
|
|
200:
|
|
description: Your account has successfully been created, and you can now log in.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
400:
|
|
$ref: '#/components/responses/MalformedBody'
|
|
401:
|
|
$ref: '#/components/responses/InvalidToken'
|
|
500:
|
|
$ref: '#/components/responses/ServerError'
|
|
|
|
components:
|
|
requestBodies:
|
|
AuthCredentials:
|
|
description: User credentials.
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
required:
|
|
- username
|
|
- password
|
|
type: object
|
|
properties:
|
|
username:
|
|
type: string
|
|
description: The username of the user.
|
|
password:
|
|
type: string
|
|
description: The password of the user.
|
|
TokenRequest:
|
|
description: The access token to identify a user.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
required:
|
|
- token
|
|
properties:
|
|
token:
|
|
type: string
|
|
description: The access token.
|
|
responses:
|
|
MalformedBody:
|
|
description: The information in your body is incomplete, or your JSON format is invalid.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
example:
|
|
reason: Invalid request body provided.
|
|
code: 400
|
|
InvalidCredentials:
|
|
description: The credentials you have provided are incorrect.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
example:
|
|
reason: The username or password provided are incorrect.
|
|
code: 401
|
|
InvalidToken:
|
|
description: The access token you provided is invalid or missing.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
example:
|
|
reason: The token provided is invalid.
|
|
code: 401
|
|
ServerError:
|
|
description: The server could not complete a request due to an unknown error. More informatino may be available in the description.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
example:
|
|
reason: The internal server reached an unknown state.
|
|
code: 500
|
|
schemas:
|
|
RegisteredUser:
|
|
type: object
|
|
required:
|
|
- username
|
|
- email
|
|
- password
|
|
properties:
|
|
username:
|
|
type: string
|
|
minLength: 3
|
|
maxLength: 16
|
|
pattern: "[a-zA-Z0-9 ]{3,16}"
|
|
description: A Unique uusername to identify a user around the website.
|
|
email:
|
|
type: string
|
|
format: email
|
|
description: A Unique email used for communication/further identification.
|
|
password:
|
|
type: string
|
|
format: password
|
|
minLength: 8
|
|
maxLength: 32
|
|
Token:
|
|
required:
|
|
- token
|
|
type: object
|
|
properties:
|
|
token:
|
|
type: string
|
|
description: The access token value
|
|
Error:
|
|
required:
|
|
- reason
|
|
- code
|
|
type: object
|
|
properties:
|
|
reason:
|
|
type: string
|
|
description: The cause of the error message
|
|
code:
|
|
type: integer
|
|
description: The HTTP error code value accompanying the error. |