swagger: add login endpoint + base details
parent
51cce4ec03
commit
0dde95ee8e
@ -0,0 +1,99 @@
|
|||||||
|
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'
|
||||||
|
|
||||||
|
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.
|
||||||
|
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
|
||||||
|
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:
|
||||||
|
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.
|
Loading…
Reference in New Issue