Added schema documentation

This commit is contained in:
Keannu Bernasol 2023-11-09 19:52:03 +08:00
parent 1c56369044
commit 2d0e602ba1
14 changed files with 732 additions and 1 deletions

Binary file not shown.

View file

@ -66,6 +66,8 @@ INSTALLED_APPS = [
'rest_framework_simplejwt',
'djoser',
'corsheaders',
'drf_spectacular',
'drf_spectacular_sidecar',
'accounts'
]
@ -125,6 +127,19 @@ REST_FRAMEWORK = {
'user': '1440/min'
},
'DEFAULT_SCHEMA_CLASS': 'drf_spectacular.openapi.AutoSchema',
}
# DRF-Spectacular
SPECTACULAR_SETTINGS = {
'TITLE': 'CITC Equipment Tracker Backend',
'DESCRIPTION': 'An IT Elective 4 Project',
'VERSION': '1.0.0',
'SERVE_INCLUDE_SCHEMA': False,
'SWAGGER_UI_DIST': 'SIDECAR',
'SWAGGER_UI_FAVICON_HREF': 'SIDECAR',
'REDOC_DIST': 'SIDECAR',
# OTHER SETTINGS
}
WSGI_APPLICATION = 'config.wsgi.application'

View file

@ -16,8 +16,14 @@ Including another URLconf
"""
from django.contrib import admin
from django.urls import path, include
from drf_spectacular.views import SpectacularAPIView, SpectacularRedocView, SpectacularSwaggerView
urlpatterns = [
path('admin/', admin.site.urls),
path('api/v1/', include('api.urls'))
path('api/v1/', include('api.urls')),
path('schema/', SpectacularAPIView.as_view(), name='schema'),
path('swagger/',
SpectacularSwaggerView.as_view(url_name='schema'), name='swagger-ui'),
path('redoc/',
SpectacularRedocView.as_view(url_name='schema'), name='redoc'),
]

View file

@ -0,0 +1,710 @@
openapi: 3.0.3
info:
title: CITC Equipment Tracker Backend
version: 1.0.0
description: An IT Elective 4 Project
paths:
/api/v1/accounts/jwt/create/:
post:
operationId: api_v1_accounts_jwt_create_create
description: |-
Takes a set of user credentials and returns an access and refresh JSON web
token pair to prove the authentication of those credentials.
tags:
- api
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/TokenObtainPair'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/TokenObtainPair'
multipart/form-data:
schema:
$ref: '#/components/schemas/TokenObtainPair'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/TokenObtainPair'
description: ''
/api/v1/accounts/jwt/refresh/:
post:
operationId: api_v1_accounts_jwt_refresh_create
description: |-
Takes a refresh type JSON web token and returns an access type JSON web
token if the refresh token is valid.
tags:
- api
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/TokenRefresh'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/TokenRefresh'
multipart/form-data:
schema:
$ref: '#/components/schemas/TokenRefresh'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/TokenRefresh'
description: ''
/api/v1/accounts/jwt/verify/:
post:
operationId: api_v1_accounts_jwt_verify_create
description: |-
Takes a token and indicates if it is valid. This view provides no
information about a token's fitness for a particular use.
tags:
- api
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/TokenVerify'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/TokenVerify'
multipart/form-data:
schema:
$ref: '#/components/schemas/TokenVerify'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/TokenVerify'
description: ''
/api/v1/accounts/users/:
get:
operationId: api_v1_accounts_users_list
tags:
- api
security:
- jwtAuth: []
responses:
'200':
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/CustomUser'
description: ''
post:
operationId: api_v1_accounts_users_create
tags:
- api
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UserRegistration'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/UserRegistration'
multipart/form-data:
schema:
$ref: '#/components/schemas/UserRegistration'
required: true
security:
- jwtAuth: []
- {}
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/UserRegistration'
description: ''
/api/v1/accounts/users/{id}/:
get:
operationId: api_v1_accounts_users_retrieve
parameters:
- in: path
name: id
schema:
type: integer
description: A unique integer value identifying this user.
required: true
tags:
- api
security:
- jwtAuth: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CustomUser'
description: ''
put:
operationId: api_v1_accounts_users_update
parameters:
- in: path
name: id
schema:
type: integer
description: A unique integer value identifying this user.
required: true
tags:
- api
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CustomUser'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/CustomUser'
multipart/form-data:
schema:
$ref: '#/components/schemas/CustomUser'
required: true
security:
- jwtAuth: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CustomUser'
description: ''
patch:
operationId: api_v1_accounts_users_partial_update
parameters:
- in: path
name: id
schema:
type: integer
description: A unique integer value identifying this user.
required: true
tags:
- api
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PatchedCustomUser'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/PatchedCustomUser'
multipart/form-data:
schema:
$ref: '#/components/schemas/PatchedCustomUser'
security:
- jwtAuth: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CustomUser'
description: ''
delete:
operationId: api_v1_accounts_users_destroy
parameters:
- in: path
name: id
schema:
type: integer
description: A unique integer value identifying this user.
required: true
tags:
- api
security:
- jwtAuth: []
responses:
'204':
description: No response body
/api/v1/accounts/users/activation/:
post:
operationId: api_v1_accounts_users_activation_create
tags:
- api
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Activation'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/Activation'
multipart/form-data:
schema:
$ref: '#/components/schemas/Activation'
required: true
security:
- jwtAuth: []
- {}
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Activation'
description: ''
/api/v1/accounts/users/me/:
get:
operationId: api_v1_accounts_users_me_retrieve
tags:
- api
security:
- jwtAuth: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CustomUser'
description: ''
put:
operationId: api_v1_accounts_users_me_update
tags:
- api
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CustomUser'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/CustomUser'
multipart/form-data:
schema:
$ref: '#/components/schemas/CustomUser'
required: true
security:
- jwtAuth: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CustomUser'
description: ''
patch:
operationId: api_v1_accounts_users_me_partial_update
tags:
- api
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PatchedCustomUser'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/PatchedCustomUser'
multipart/form-data:
schema:
$ref: '#/components/schemas/PatchedCustomUser'
security:
- jwtAuth: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CustomUser'
description: ''
delete:
operationId: api_v1_accounts_users_me_destroy
tags:
- api
security:
- jwtAuth: []
responses:
'204':
description: No response body
/api/v1/accounts/users/resend_activation/:
post:
operationId: api_v1_accounts_users_resend_activation_create
tags:
- api
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SendEmailReset'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/SendEmailReset'
multipart/form-data:
schema:
$ref: '#/components/schemas/SendEmailReset'
required: true
security:
- jwtAuth: []
- {}
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/SendEmailReset'
description: ''
/api/v1/accounts/users/reset_password/:
post:
operationId: api_v1_accounts_users_reset_password_create
tags:
- api
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SendEmailReset'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/SendEmailReset'
multipart/form-data:
schema:
$ref: '#/components/schemas/SendEmailReset'
required: true
security:
- jwtAuth: []
- {}
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/SendEmailReset'
description: ''
/api/v1/accounts/users/reset_password_confirm/:
post:
operationId: api_v1_accounts_users_reset_password_confirm_create
tags:
- api
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PasswordResetConfirm'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/PasswordResetConfirm'
multipart/form-data:
schema:
$ref: '#/components/schemas/PasswordResetConfirm'
required: true
security:
- jwtAuth: []
- {}
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/PasswordResetConfirm'
description: ''
/api/v1/accounts/users/reset_username/:
post:
operationId: api_v1_accounts_users_reset_username_create
tags:
- api
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SendEmailReset'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/SendEmailReset'
multipart/form-data:
schema:
$ref: '#/components/schemas/SendEmailReset'
required: true
security:
- jwtAuth: []
- {}
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/SendEmailReset'
description: ''
/api/v1/accounts/users/reset_username_confirm/:
post:
operationId: api_v1_accounts_users_reset_username_confirm_create
tags:
- api
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UsernameResetConfirm'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/UsernameResetConfirm'
multipart/form-data:
schema:
$ref: '#/components/schemas/UsernameResetConfirm'
required: true
security:
- jwtAuth: []
- {}
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/UsernameResetConfirm'
description: ''
/api/v1/accounts/users/set_password/:
post:
operationId: api_v1_accounts_users_set_password_create
tags:
- api
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SetPassword'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/SetPassword'
multipart/form-data:
schema:
$ref: '#/components/schemas/SetPassword'
required: true
security:
- jwtAuth: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/SetPassword'
description: ''
/api/v1/accounts/users/set_username/:
post:
operationId: api_v1_accounts_users_set_username_create
tags:
- api
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SetUsername'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/SetUsername'
multipart/form-data:
schema:
$ref: '#/components/schemas/SetUsername'
required: true
security:
- jwtAuth: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/SetUsername'
description: ''
components:
schemas:
Activation:
type: object
properties:
uid:
type: string
token:
type: string
required:
- token
- uid
CustomUser:
type: object
properties:
username:
type: string
readOnly: true
description: Required. 150 characters or fewer. Letters, digits and @/./+/-/_
only.
email:
type: string
format: email
title: Email address
maxLength: 254
avatar:
type: string
format: uri
first_name:
type: string
maxLength: 100
last_name:
type: string
maxLength: 100
required:
- avatar
- first_name
- last_name
- username
PasswordResetConfirm:
type: object
properties:
uid:
type: string
token:
type: string
new_password:
type: string
required:
- new_password
- token
- uid
PatchedCustomUser:
type: object
properties:
username:
type: string
readOnly: true
description: Required. 150 characters or fewer. Letters, digits and @/./+/-/_
only.
email:
type: string
format: email
title: Email address
maxLength: 254
avatar:
type: string
format: uri
first_name:
type: string
maxLength: 100
last_name:
type: string
maxLength: 100
SendEmailReset:
type: object
properties:
email:
type: string
format: email
required:
- email
SetPassword:
type: object
properties:
new_password:
type: string
current_password:
type: string
required:
- current_password
- new_password
SetUsername:
type: object
properties:
current_password:
type: string
new_username:
type: string
title: Username
description: Required. 150 characters or fewer. Letters, digits and @/./+/-/_
only.
pattern: ^[\w.@+-]+$
maxLength: 150
required:
- current_password
- new_username
TokenObtainPair:
type: object
properties:
username:
type: string
writeOnly: true
password:
type: string
writeOnly: true
access:
type: string
readOnly: true
refresh:
type: string
readOnly: true
required:
- access
- password
- refresh
- username
TokenRefresh:
type: object
properties:
access:
type: string
readOnly: true
refresh:
type: string
writeOnly: true
required:
- access
- refresh
TokenVerify:
type: object
properties:
token:
type: string
writeOnly: true
required:
- token
UserRegistration:
type: object
properties:
username:
type: string
description: Required. 150 characters or fewer. Letters, digits and @/./+/-/_
only.
pattern: ^[\w.@+-]+$
maxLength: 150
email:
type: string
format: email
password:
type: string
writeOnly: true
avatar:
type: string
format: uri
nullable: true
first_name:
type: string
maxLength: 100
last_name:
type: string
maxLength: 100
required:
- email
- first_name
- last_name
- password
- username
UsernameResetConfirm:
type: object
properties:
new_username:
type: string
title: Username
description: Required. 150 characters or fewer. Letters, digits and @/./+/-/_
only.
pattern: ^[\w.@+-]+$
maxLength: 150
required:
- new_username
securitySchemes:
jwtAuth:
type: http
scheme: bearer
bearerFormat: JWT