Clyde/Documents/proto/general/openapi.yaml

465 lines
11 KiB
YAML
Raw Normal View History

2023-12-04 19:58:00 +01:00
openapi: 3.0.0
info:
title: ClydeAPI
2023-12-10 21:21:11 +01:00
description:
This is the Clyde's api documentation. <br/>
Each endpoints are organised by endpoints **AND** by extensions making it easier to navigate.
2023-12-04 19:58:00 +01:00
version: 0.0.1
servers:
- url: https://clyde.herisson.ovh/api
description: default api point for clyde's service
paths:
/ping:
get:
2023-12-08 15:48:09 +01:00
summary: Check the API status
2023-12-04 19:58:00 +01:00
responses:
default:
2023-12-08 15:48:09 +01:00
description: pong
2023-12-04 19:58:00 +01:00
content:
text/plain:
schema:
type: string
example: pong
2023-12-05 20:47:12 +01:00
/users:
get:
2023-12-08 15:48:09 +01:00
summary: list all users
2023-12-05 20:47:12 +01:00
tags:
2023-12-10 21:26:51 +01:00
- General
2023-12-05 20:47:12 +01:00
- SI
2023-12-04 19:58:00 +01:00
security:
- bearer: []
2023-12-07 23:27:23 +01:00
parameters:
- in: query
name: type
required: false
schema:
type: string
enum: [teacher, student, secretary]
2023-12-05 20:47:12 +01:00
responses:
2023-12-07 23:27:23 +01:00
'200':
2023-12-08 13:34:12 +01:00
description: OK
2023-12-07 23:27:23 +01:00
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/User"
'401':
$ref: '#/components/responses/UnauthorizedError'
2023-12-05 20:47:12 +01:00
2023-12-07 23:27:23 +01:00
/user:
get:
2023-12-08 15:48:09 +01:00
summary: get informations about yourself
2023-12-07 23:27:23 +01:00
tags:
2023-12-10 21:26:51 +01:00
- General
2023-12-07 23:27:23 +01:00
- Users
2023-12-10 21:21:11 +01:00
security:
- bearer: []
2023-12-07 23:27:23 +01:00
responses:
'200':
description: Ok
content:
application/json:
schema:
$ref: "#/components/schemas/User"
2023-12-10 21:21:11 +01:00
'401':
$ref: '#/components/responses/UnauthorizedError'
2023-12-05 20:47:12 +01:00
post:
2023-12-08 15:48:09 +01:00
summary: Create user
2023-12-05 20:47:12 +01:00
tags:
2023-12-10 21:26:51 +01:00
- General
2023-12-07 23:27:23 +01:00
- Users
requestBody:
2023-12-08 13:34:12 +01:00
required: true
2023-12-07 23:27:23 +01:00
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")
example:
{
"LastName": "Doe" ,
"FirstName": "John",
"Email": "John.Doe@example.com",
"Address": {
2023-12-08 15:48:09 +01:00
"Address": "Rue de Tournais 42",
2023-12-07 23:27:23 +01:00
"Country": "BE"},
"BirthDate": "1941-02-22",
}
2023-12-04 19:58:00 +01:00
responses:
2023-12-07 23:27:23 +01:00
'201':
2023-12-04 19:58:00 +01:00
description: User created
'401':
$ref: '#/components/responses/UnauthorizedError'
2023-12-05 20:47:12 +01:00
patch:
2023-12-08 15:48:09 +01:00
summary: Change informations about yourself
2023-12-05 20:47:12 +01:00
tags:
2023-12-10 21:26:51 +01:00
- General
2023-12-07 23:27:23 +01:00
- Users
2023-12-05 20:47:12 +01:00
security:
- bearer: []
2023-12-07 23:27:23 +01:00
requestBody:
2023-12-08 13:34:12 +01:00
required: true
2023-12-07 23:27:23 +01:00
content:
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/User'
2023-12-05 20:47:12 +01:00
responses:
2023-12-07 23:27:23 +01:00
'201':
2023-12-08 15:48:09 +01:00
description: Successfully changed.
2023-12-05 20:47:12 +01:00
'401':
$ref: '#/components/responses/UnauthorizedError'
2023-12-04 19:58:00 +01:00
/user/{mat}:
2023-12-08 15:48:09 +01:00
parameters:
- name: mat
in: path
description: Matricule of the user (unique id)
required: true
schema:
type: integer
2023-12-04 19:58:00 +01:00
get:
2023-12-08 15:48:09 +01:00
summary: Get user's informations
2023-12-04 19:58:00 +01:00
tags:
2023-12-10 21:26:51 +01:00
- General
2023-12-05 20:47:12 +01:00
- Admin
2023-12-04 19:58:00 +01:00
responses:
'200':
2023-12-08 15:48:09 +01:00
description: User found
2023-12-04 19:58:00 +01:00
content:
application/json:
schema:
$ref: "#/components/schemas/User"
2023-12-05 20:47:12 +01:00
patch:
2023-12-08 15:48:09 +01:00
summary: Alter user's informations
2023-12-05 20:47:12 +01:00
tags:
2023-12-10 21:26:51 +01:00
- General
2023-12-05 20:47:12 +01:00
- Admin
security:
- bearer: []
2023-12-07 23:27:23 +01:00
requestBody:
2023-12-08 13:34:12 +01:00
required: true
2023-12-07 23:27:23 +01:00
content:
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/User'
2023-12-05 20:47:12 +01:00
responses:
2023-12-07 23:27:23 +01:00
'201':
2023-12-08 15:48:09 +01:00
description: Successfully changed
2023-12-05 20:47:12 +01:00
'401':
$ref: '#/components/responses/UnauthorizedError'
2023-12-07 23:27:23 +01:00
/course:
post:
2023-12-08 15:48:09 +01:00
summary: Create new course
2023-12-05 20:47:12 +01:00
tags:
2023-12-10 21:26:51 +01:00
- General
2023-12-07 23:27:23 +01:00
- Courses
- Secretariat
security:
2023-12-05 20:47:12 +01:00
- bearer: []
2023-12-07 23:27:23 +01:00
requestBody:
2023-12-08 13:34:12 +01:00
required: true
2023-12-07 23:27:23 +01:00
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
name:
type: string
courses:
type: array
items:
type: string
2023-12-05 20:47:12 +01:00
responses:
2023-12-07 23:27:23 +01:00
'201':
2023-12-08 15:48:09 +01:00
description: course created
2023-12-05 20:47:12 +01:00
'401':
$ref: '#/components/responses/UnauthorizedError'
2023-12-04 19:58:00 +01:00
/courses/{id}:
get:
2023-12-08 15:48:09 +01:00
summary: see courses informations
2023-12-04 19:58:00 +01:00
tags:
2023-12-10 21:26:51 +01:00
- General
2023-12-04 19:58:00 +01:00
- Courses
responses:
2023-12-07 23:27:23 +01:00
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Course'
2023-12-05 20:47:12 +01:00
parameters:
- name: id
in: path
required: true
schema:
type: integer
delete:
2023-12-08 15:48:09 +01:00
summary: delete a course
2023-12-05 20:47:12 +01:00
tags:
2023-12-10 21:26:51 +01:00
- General
2023-12-05 20:47:12 +01:00
- Courses
2023-12-07 23:27:23 +01:00
- Secretariat
2023-12-05 20:47:12 +01:00
security:
- bearer: []
responses:
2023-12-07 23:27:23 +01:00
'201':
description: Success
'401':
$ref: '#/components/responses/UnauthorizedError'
2023-12-05 20:47:12 +01:00
patch:
2023-12-08 15:48:09 +01:00
summary: Change course options
2023-12-04 19:58:00 +01:00
tags:
2023-12-10 21:26:51 +01:00
- General
2023-12-07 23:27:23 +01:00
- Secretariat
2023-12-04 19:58:00 +01:00
- Courses
2023-12-05 20:47:12 +01:00
security:
- bearer: []
2023-12-07 23:27:23 +01:00
requestBody:
2023-12-08 13:34:12 +01:00
required: true
2023-12-07 23:27:23 +01:00
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
name:
type: string
credits:
type: integer
faculty:
type: string
teachers:
type: object
$ref: '#/components/schemas/User'
assistants:
type: array
items:
$ref: '#/components/schemas/User'
example:
{
"name": "Math pour l'info",
"credits": 11,
"faculty": "science",
"Teacher": ,
"Assistants": [ ]
}
2023-12-05 20:47:12 +01:00
responses:
2023-12-07 23:27:23 +01:00
'201':
2023-12-08 15:48:09 +01:00
description: Course modified
2023-12-07 23:27:23 +01:00
'401':
$ref: '#/components/responses/UnauthorizedError'
2023-12-05 20:47:12 +01:00
/cursus:
post:
2023-12-08 15:48:09 +01:00
summary: Create a cursus
2023-12-05 20:47:12 +01:00
tags:
2023-12-10 21:26:51 +01:00
- General
2023-12-05 20:47:12 +01:00
- cursus
2023-12-04 19:58:00 +01:00
security:
- bearer: []
2023-12-07 23:27:23 +01:00
requestBody:
2023-12-08 13:34:12 +01:00
required: true
2023-12-07 23:27:23 +01:00
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
name:
type: string
2023-12-08 15:48:09 +01:00
courses:
type: array
2023-12-07 23:27:23 +01:00
items:
2023-12-08 15:48:09 +01:00
type: integer
description: id of courses
2023-12-07 23:27:23 +01:00
example:
{
2023-12-08 15:48:09 +01:00
"name": "Bac1",
[]
2023-12-07 23:27:23 +01:00
}
2023-12-04 19:58:00 +01:00
responses:
2023-12-07 23:27:23 +01:00
'201':
2023-12-08 15:48:09 +01:00
description: Cursus created
2023-12-07 23:27:23 +01:00
'401':
$ref: '#/components/responses/UnauthorizedError'
2023-12-05 20:47:12 +01:00
/cursus/{id}:
get:
2023-12-08 15:48:09 +01:00
summary: See Cursus's informations
2023-12-05 20:47:12 +01:00
tags:
2023-12-10 21:26:51 +01:00
- General
2023-12-05 20:47:12 +01:00
- cursus
responses:
2023-12-07 23:27:23 +01:00
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Cursus'
2023-12-05 20:47:12 +01:00
parameters:
- name: id
in: path
required: true
schema:
type: integer
2023-12-04 19:58:00 +01:00
delete:
2023-12-08 15:48:09 +01:00
summary: Delete cursus
2023-12-05 20:47:12 +01:00
tags:
2023-12-10 21:26:51 +01:00
- General
2023-12-05 20:47:12 +01:00
- cursus
security:
- bearer: []
responses:
2023-12-07 23:27:23 +01:00
'201':
description: Success
'401':
$ref: '#/components/responses/UnauthorizedError'
2023-12-05 20:47:12 +01:00
patch:
2023-12-08 15:48:09 +01:00
summary: Modify cursus
2023-12-05 20:47:12 +01:00
tags:
2023-12-10 21:26:51 +01:00
- General
2023-12-05 20:47:12 +01:00
- cursus
security:
- bearer: []
2023-12-07 23:27:23 +01:00
requestBody:
2023-12-08 13:34:12 +01:00
required: true
2023-12-07 23:27:23 +01:00
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
name:
type: string
credits:
type: integer
faculty:
type: string
teachers:
type: object
$ref: '#/components/schemas/User'
assistants:
type: array
items:
$ref: '#/components/schemas/User'
example:
{
"name": "Math pour l'info",
"credits": 11,
"faculty": "science",
"Teacher": ,
"Assistants": [ ]
}
2023-12-05 20:47:12 +01:00
responses:
2023-12-07 23:27:23 +01:00
'201':
2023-12-08 15:48:09 +01:00
description: Cursus modified
2023-12-07 23:27:23 +01:00
'401':
$ref: '#/components/responses/UnauthorizedError'
2023-12-05 20:47:12 +01:00
2023-12-04 19:58:00 +01:00
components:
securitySchemes:
bearer:
type: http
scheme: bearer
schemas:
User:
type: object
properties:
2023-12-07 23:27:23 +01:00
regNo:
2023-12-04 19:58:00 +01:00
type: integer
2023-12-07 23:27:23 +01:00
photo:
2023-12-04 19:58:00 +01:00
type: object
2023-12-07 23:27:23 +01:00
lastName:
2023-12-04 19:58:00 +01:00
type: string
2023-12-07 23:27:23 +01:00
firstName:
2023-12-04 19:58:00 +01:00
type: string
2023-12-07 23:27:23 +01:00
email:
2023-12-04 19:58:00 +01:00
type: string
2023-12-07 23:27:23 +01:00
address:
2023-12-04 19:58:00 +01:00
$ref: "#/components/schemas/Address"
2023-12-07 23:27:23 +01:00
birthDate:
2023-12-04 19:58:00 +01:00
type: string
description: Follow the iso 8601 ("YYYY-MM-DD")
example:
{
2023-12-07 23:27:23 +01:00
"regNo": 42,
"lastName": "Doe" ,
"firstName": "John",
"email": "John.Doe@example.com",
"address": {
2023-12-10 21:21:11 +01:00
"address": "Rue de Tournais 42",
2023-12-07 23:27:23 +01:00
"country": "BE"},
"birthDate": "1941-02-22",
"staffMember": true,
2023-12-04 19:58:00 +01:00
}
Address:
type: object
properties:
2023-12-07 23:27:23 +01:00
address:
2023-12-04 19:58:00 +01:00
type: string
2023-12-07 23:27:23 +01:00
country:
2023-12-04 19:58:00 +01:00
type: string
description: Follow the ISO-3166-1 alpha-2 standard.
example:
{
2023-12-10 21:21:11 +01:00
"address": "Rue de Tournais 42",
2023-12-07 23:27:23 +01:00
"country": "BE"
}
Course:
type: object
properties:
id:
type: integer
name:
type: string
credits:
type: integer
faculty:
type: string
teachers:
2023-12-08 15:48:09 +01:00
type: integer
description: user's id
2023-12-07 23:27:23 +01:00
assistants:
type: array
items:
2023-12-08 15:48:09 +01:00
type: integer
description: user's id
2023-12-07 23:27:23 +01:00
example:
{
"id": 42,
"name": "Math pour l'info",
"credits": 11,
"faculty": "science",
2023-12-08 15:48:09 +01:00
"Teacher": 42,
2023-12-07 23:27:23 +01:00
"Assistants": [ ]
2023-12-04 19:58:00 +01:00
}
Cursus:
type: object
properties:
2023-12-07 23:27:23 +01:00
id:
2023-12-04 19:58:00 +01:00
type: integer
2023-12-07 23:27:23 +01:00
name:
type: string
courses:
2023-12-04 19:58:00 +01:00
type: array
items:
type: string
example:
{
"id": 42,
"courses": ['Math', 'Info']
}
responses:
UnauthorizedError:
2023-12-08 15:48:09 +01:00
description: Unauthorized access or missing bearer