Clyde/Documents/proto/general/openapi.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

tags:
  - name: default
  - name: General
    description: General endpoints 
  - name: Ext (scientific articles)
    description: Scientifics articles extension's endpoints
  - name: Ext (Schedule)
    description: Schedule extension's endpoints

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