diff --git a/Documents/proto/general/openapi.yaml b/Documents/proto/general/openapi.yaml index 4c74faa..5054813 100644 --- a/Documents/proto/general/openapi.yaml +++ b/Documents/proto/general/openapi.yaml @@ -1,7 +1,9 @@ openapi: 3.0.0 info: title: ClydeAPI - description: Clyde's api + description: + This is the Clyde's api documentation.
+ Each endpoints are organised by endpoints **AND** by extensions making it easier to navigate. version: 0.0.1 servers: @@ -11,39 +13,116 @@ servers: paths: /ping: get: - summary: Test if the api is up. + summary: Check the API status responses: default: - description: Standard response to ping + description: pong content: text/plain: schema: type: string example: pong - /user: - put: - summary: create a new user + /users: + get: + summary: list all users tags: - - users + - General + - SI + security: + - bearer: [] + parameters: + - in: query + name: type + required: false + schema: + type: string + enum: [teacher, student, secretary] + 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: User created - '401': - $ref: '#/components/responses/UnauthorizedError' - /user/{mat}: - get: - summary: get user's info - tags: - - users - responses: - '200': - description: User found + 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") + example: + { + "LastName": "Doe" , + "FirstName": "John", + "Email": "John.Doe@example.com", + "Address": { + "Address": "Rue de Tournais 42", + "Country": "BE"}, + "BirthDate": "1941-02-22", + } + 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/{mat}: parameters: - name: mat in: path @@ -51,42 +130,241 @@ paths: required: true schema: type: integer - - /cursus/{id}: get: - summary: Voir les informations sur un Cursus + 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 + 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}: + get: + summary: see courses informations + tags: + - General - Courses responses: '200': - description: Cursus found + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Course' + parameters: + - name: id + in: path + required: true + schema: + type: integer + 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: 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": [ ] + } + 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' - /courses/{id}: - get: - summary: Voir les informations sur un cours* - tags: - - Courses - responses: - - put: - summary: Créer un nouveau cours - tags: - - Courses - security: - - bearer: [] - responses: - + parameters: + - name: id + in: path + required: true + schema: + type: integer delete: - summary: Suprimer un cours + summary: Delete cursus tags: - - Courses + - 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: + 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": [ ] + } + responses: + '201': + description: Cursus modified + '401': + $ref: '#/components/responses/UnauthorizedError' + components: securitySchemes: @@ -97,54 +375,82 @@ components: User: type: object properties: - RegNo: + regNo: type: integer - Photo: + photo: type: object - LastName: + lastName: type: string - FirstName: + firstName: type: string - Email: + email: type: string - Address: + address: $ref: "#/components/schemas/Address" - BirthDate: + birthDate: type: string description: Follow the iso 8601 ("YYYY-MM-DD") - StaffMember: - type: boolean example: { - "RegNo": 42, - "LastName": "Doe" , - "FirstName": "John", - "Email": "John.Doe@example.com", - "Address": { - "Address": "Rue de Tounais 42", - "Country": "BE"}, - "BirthDate": "1941-02-22", - "StaffMember": true + "regNo": 42, + "lastName": "Doe" , + "firstName": "John", + "email": "John.Doe@example.com", + "address": { + "address": "Rue de Tournais 42", + "country": "BE"}, + "birthDate": "1941-02-22", + "staffMember": true, } Address: type: object properties: - Address: + address: type: string - Country: + country: type: string description: Follow the ISO-3166-1 alpha-2 standard. example: { - "Address": "Rue de Tounais 42", - "Country": "BE" + "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: + id: type: integer - Courses: + name: + type: string + courses: type: array items: type: string @@ -155,4 +461,4 @@ components: } responses: UnauthorizedError: - description: Access token is missing or invalid + description: Unauthorized access or missing bearer