Clyde/Documents/proto/general/openapi.yaml
2023-12-13 16:26:15 +01:00

1019 lines
24 KiB
YAML

openapi: 3.0.0
info:
title: ClydeAPI
description:
This is the Clyde's api documentation. <br/>
Each endpoints are organised by endpoints **AND** by extensions making it easier to navigate.
version: 0.0.1
servers:
- url: https://clyde.herisson.ovh/api
description: default api point for clyde's service
paths:
/ping:
get:
summary: Check the API status
responses:
default:
description: pong
content:
text/plain:
schema:
type: string
example: pong
/users:
get:
summary: list all users
tags:
- General
- SI
security:
- bearer: []
parameters:
- in: query
name: type
required: false
schema:
$ref: '#components/schemas/Roles'
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/User"
'401':
$ref: '#/components/responses/UnauthorizedError'
/user:
get:
summary: get informations about yourself
tags:
- General
- Users
security:
- bearer: []
responses:
'200':
description: Ok
content:
application/json:
schema:
$ref: "#/components/schemas/User"
'401':
$ref: '#/components/responses/UnauthorizedError'
post:
summary: Create user
tags:
- General
- Users
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
LastName:
type: string
FirstName:
type: string
Email:
type: string
Address:
$ref: "#/components/schemas/Address"
BirthDate:
type: string
description: Follow the iso 8601 ("YYYY-MM-DD")
Role:
$ref: "#/components/schemas/Roles"
example:
{
"LastName": "Doe" ,
"FirstName": "John",
"Email": "John.Doe@example.com",
"Address": {
"Address": "Rue de Tournais 42",
"Country": "BE"},
"BirthDate": "1941-02-22",
"Role": "student"
}
responses:
'201':
description: User created
'401':
$ref: '#/components/responses/UnauthorizedError'
patch:
summary: Change informations about yourself
tags:
- General
- Users
security:
- bearer: []
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/User'
responses:
'201':
description: Successfully changed.
'401':
$ref: '#/components/responses/UnauthorizedError'
/user/{RegNo}:
parameters:
- name: RegNo
in: path
description: Regestration number of the user (unique id)
required: true
schema:
type: integer
get:
summary: Get user's informations
tags:
- General
- Admin
responses:
'200':
description: User found
content:
application/json:
schema:
$ref: "#/components/schemas/User"
patch:
summary: Alter user's informations
tags:
- General
- Admin
- Secretariat
- Ext (scientific articles)
security:
- bearer: []
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/User'
responses:
'201':
description: Successfully changed
'401':
$ref: '#/components/responses/UnauthorizedError'
/course:
post:
summary: Create new course
tags:
- General
- Courses
- Secretariat
security:
- bearer: []
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
name:
type: string
courses:
type: array
items:
type: string
responses:
'201':
description: course created
'401':
$ref: '#/components/responses/UnauthorizedError'
/courses/{id}:
parameters:
- name: id
in: path
required: true
schema:
type: integer
get:
summary: see courses informations
tags:
- General
- Courses
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Course'
delete:
summary: delete a course
tags:
- General
- Courses
- Secretariat
security:
- bearer: []
responses:
'201':
description: Success
'401':
$ref: '#/components/responses/UnauthorizedError'
patch:
summary: Change course options
tags:
- General
- Secretariat
- Courses
security:
- bearer: []
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
name:
type: string
credits:
type: integer
faculty:
type: string
teachers:
type: integer
description: Teacher's identifier
assistants:
type: array
items:
$ref: '#/components/schemas/User'
example:
{
"name": "Math pour l'info",
"credits": 11,
"faculty": "science",
"Teacher": ,
"Assistants": [ ]
}
responses:
'201':
description: Course modified
'401':
$ref: '#/components/responses/UnauthorizedError'
/cursus:
post:
summary: Create a cursus
tags:
- General
- Cursus
security:
- bearer: []
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
name:
type: string
courses:
type: array
items:
type: integer
description: id of courses
example:
{
"name": "Bac1",
[]
}
responses:
'201':
description: Cursus created
'401':
$ref: '#/components/responses/UnauthorizedError'
/cursus/{id}:
get:
summary: See Cursus's informations
tags:
- General
- Cursus
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Cursus'
parameters:
- name: id
in: path
required: true
schema:
type: integer
delete:
summary: Delete cursus
tags:
- General
- Cursus
security:
- bearer: []
responses:
'201':
description: Success
'401':
$ref: '#/components/responses/UnauthorizedError'
patch:
summary: Modify cursus
tags:
- General
- Cursus
security:
- bearer: []
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
name:
type: string
credits:
type: integer
faculty:
type: string
teachers:
$ref: '#/components/schemas/User'
assistants:
type: array
items:
$ref: '#/components/schemas/User'
example:
{
"name": "Math pour l'info",
"credits": 11,
"faculty": "science",
"Teacher": ,
"Assistants": [ ]
}
responses:
'201':
description: Cursus modified
'401':
$ref: '#/components/responses/UnauthorizedError'
/lesson:
post:
summary: create a new lesson
tags:
- Secretariat
- Lesson
- Ext (Schedule)
security:
- bearer: []
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
date:
type: string
description: Follow the iso 8601 ("YYYY-MM-DD")
CourseId:
type: integer
duration:
type: number
classroom:
type: string
responses:
'201':
description: Lesson created
'401':
$ref: '#/components/responses/UnauthorizedError'
/lesson/{id}:
parameters:
- name: id
in: path
required: true
schema:
type: integer
get:
summary : See lesson's informations
tags:
- Users
- Lesson
- Ext (Schedule)
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Lesson'
patch:
summary : Modify Lesson
tags:
- Secretariat
- Lesson
- Ext (Schedule)
security:
- bearer: []
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
date:
type: string
description: Follow the iso 8601 ("YYYY-MM-DD")
IDcourse:
type: integer
duration:
type: number
classroom:
type: string
responses:
'201':
description: Lesson modified
'401':
$ref: '#/components/responses/UnauthorizedError'
delete:
summary: Delete lesson
tags:
- Lesson
- Secretariat
- Ext (Schedule)
security:
- bearer: []
responses:
'201':
description: Success
'401':
$ref: '#/components/responses/UnauthorizedError'
/scheduleRequest:
post:
summary: Create a new request
tags:
- Teacher
- ScheduleRequest
- Ext (Schedule)
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
requestType:
type: string
lessonId:
type: integer
newDate:
type: string
description: Follow the iso 8601 ("YYYY-MM-DD")
newClassroom:
type: string
newCourseId:
type: integer
responses:
'201':
description: Request created
'401':
$ref: '#/components/responses/UnauthorizedError'
/scheduleRequest/{id}:
parameters:
- name: id
in: path
required: true
schema:
type: integer
get:
summary : See request information
tags:
- Teacher
- Secretariat
- ScheduleRequest
- Ext (Schedule)
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ScheduleRequest'
patch:
summary : Modify request
tags:
- Teacher
- ScheduleRequest
- Ext (Schedule)
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
newDate:
type: string
newClassroom:
type: string
newCourseId:
type: integer
responses:
'201':
description: Request modified
delete:
summary: Delete request
tags:
- Teacher
- Secretariat
- ScheduleRequest
- Ext (Schedule)
responses:
'201':
description: Success
/display:
post:
summary: Create a new display
tags:
- Display
- Ext (Schedule)
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
timeMode:
type: string
displayMode:
type: string
userId:
type: integer
responses:
'201':
description: display created
/display/{id}:
parameters:
- name: id
in: path
required: true
schema:
type: integer
get:
summary : See display information
tags:
- Users
- Display
- Ext (Schedule)
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Display'
patch:
summary : Modify display
tags:
- Users
- Display
- Ext (Schedule)
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
timeMode:
type: string
displayMode:
type: string
responses:
'201':
description: Display modified
# Extension publication scientifique
/article:
post:
summary: create an article
tags:
- Ext (scientific articles)
- Researcher
security:
- bearer : []
responses:
"201" :
description: OK
'401':
$ref: '#/components/responses/UnauthorizedError'
requestBody:
required : true
content:
application/json:
schema:
type: object
properties:
pdf:
type: string
description : the B64 version encoding of the pdf file
access:
type: string
summary:
type: string
language:
type: string
title:
type: string
date:
type: string
description: Follow the iso 8601 ("YYYY-MM-DD")
views:
type: integer
example:
{
"access": "private",
"pdf": " *the b64 encoding of the pdf* ",
"summary": "looks in details about graph's second theorem",
"language": "english",
"title": "graph's second theorem study",
"date":"2023-02-01",
"views": 420,
"authors" : []
}
/article/{id}:
parameters:
- name: id
in: path
required: true
schema:
type: integer
get:
summary: get a certain article
tags:
- Users
- Ext (scientific articles)
security:
- bearer: []
responses:
"201":
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Article'
'401':
$ref: '#/components/responses/UnauthorizedError'
patch:
summary: modify an article
tags:
- Researcher
- Ext (scientific articles)
security:
- bearer : []
responses:
"201":
description: article modifié
'401':
$ref: '#/components/responses/UnauthorizedError'
requestBody:
required : true
content:
application/json:
schema:
type: object
properties:
pdf:
type: string
description : the B64 version encoding of the pdf file
access:
type: string
summary:
type: string
language:
type: string
title:
type: string
date:
type: string
description: Follow the iso 8601 ("YYYY-MM-DD")
views:
type: integer
example:
{
"access": "public",
"pdf": " *the new b64 encoding of the pdf* ",
"summary": "looks in details about the duck's algorithm problem",
"language": "english",
"title": "duck's algorithm problem solving",
"date":"2023-02-01",
"views": 10,
"authors" : []
}
delete:
summary: delete own article
tags:
- Researcher
- Ext (scientific articles)
security:
- bearer: []
responses:
'201':
description: OK
'401':
$ref: '#/components/responses/UnauthorizedError'
/DisplayArticle:
parameters:
- in: query
name: author
required: false
schema:
type: string
- in: query
name: access
required: false
schema:
type: string
enum: [public, restricted, private]
- in: query
name: name
required: false
schema:
type: string
get:
summary: get a list of article's data
tags:
- Users
- Ext (scientific articles)
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/DisplayArticle"
components:
securitySchemes:
bearer:
type: http
scheme: bearer
schemas:
User:
type: object
properties:
regNo:
type: integer
photo:
type: object
lastName:
type: string
firstName:
type: string
email:
type: string
address:
$ref: "#/components/schemas/Address"
birthDate:
type: string
description: Follow the iso 8601 ("YYYY-MM-DD")
role:
$ref: '#/components/schemas/Roles'
example:
{
"regNo": 42,
"lastName": "Doe" ,
"firstName": "John",
"email": "John.Doe@example.com",
"address": {
"address": "Rue de Tournais 42",
"country": "BE"},
"birthDate": "1941-02-22",
"role": "student"
}
Address:
type: object
properties:
address:
type: string
country:
type: string
description: Follow the ISO-3166-1 alpha-2 standard.
example:
{
"address": "Rue de Tournais 42",
"country": "BE"
}
Course:
type: object
properties:
id:
type: integer
name:
type: string
credits:
type: integer
faculty:
type: string
teachers:
type: integer
description: user's id
assistants:
type: array
items:
type: integer
description: user's id
example:
{
"id": 42,
"name": "Math pour l'info",
"credits": 11,
"faculty": "science",
"Teacher": 42,
"Assistants": [ ]
}
Cursus:
type: object
properties:
id:
type: integer
name:
type: string
courses:
type: array
items:
type: string
example:
{
"id": 42,
"courses": ['Math', 'Info']
}
Roles:
type: string
enum: [teacher, student, secretary]
Article:
type: object
properties:
articleId:
type: integer
access :
type : string
pdf :
type : string
description : file location
summary:
type : string
language:
type : string
title :
type : string
date:
type : string
views :
type : integer
authors:
type: array
items:
$ref: '#/components/schemas/User'
description: first user is the author, the remaining users are co-authors
example:
{
"articleId": 42,
"access": "private",
"pdf": "/articles/42",
"summary": "looks in details about graph's second theorem",
"language": "english",
"title": "graph's second theorem study",
"date":"2023-02-01",
"views": 420,
"authors" : []
}
DisplayArticle:
type: object
properties:
articleId:
type: integer
access:
type: string
summary:
type: string
title:
type: string
author:
type: string
items:
$ref: '#/components/schemas/User'
example:
{
"articleId": 42,
"access": "private",
"summary": "looks in details about graph's second theorem",
"title": "graph's second theorem study",
"author" : "john doe"
}
Lesson :
type: object
properties:
id:
type: integer
date:
type: string
description: Follow the iso 8601 ("YYYY-MM-DD")
duration:
type: number
description: duration of a course in hours
classroom:
type: string
courseId:
type: integer
example:
{
"id": 12,
"date": "2023-12-01",
"duration": 1.5,
"classroom": "AMPHI01",
"courseId": 12
}
ScheduleRequest:
type: object
properties:
id:
type: integer
requestType:
type: string
lessonId:
type: integer
teacherId:
type: integer
newDate:
type: string
description: Follow the iso 8601 ("YYYY-MM-DD")
newClassroom:
type: string
newCourseId:
type: integer
example:
{
"id": 12,
"requestType": "moveLesson",
"lessonId": 52,
"teacherId": 12,
"newDate": "2023-12-20",
"newClassroom":,
"newCourseId":,
}
Display:
type: object
properties:
id:
type: integer
timeMode:
type: string
description: Define the period displayed on the schedule (week,month,quadrimester..)
displayMode:
type: string
userId:
type: integer
description: Id of the user who owns this display
example:
{
"id": 12,
"timeMode": "month",
"displayMode": "grid",
"UserId": 12
}
responses:
UnauthorizedError:
description: Unauthorized access or missing bearer