OrganizerAPI/swagger.yml

swagger: "2.0"
info:
  description: "Dies ist eine API, die es ermöglicht Daten zu Stunden-, Vertretungs-, oder Klausurplänen zu erhalten."
  version: "1.0.0"
  title: "Organizer"
  termsOfService: "https://organizer.martin-luther.schule/terms"
  contact:
    email: "info@jonasfranz.software"
  license:
    name: "MIT"
    url: "https://opensource.org/licenses/MIT"
host: "api.organizer.martin-luther.schule"
basePath: "/v1"
tags:
- name: "replacement lessons"
  description: "Information about replacement and canceled lessons"
- name: "timetable"
  description: "Zugriff auf Stundenpläne"
- name: "examination scheduling"
  description: "Zugriff auf Klausurtermine"
schemes:
- "http"
- "https"
paths:
  /replacement/findAll:
    get:
      tags:
      - "replacement lessons"
      summary: "Finds all available replacement lessons"
      operationId: "findReplacementLessons"
      security:
      - passwordAuth: []
      produces: 
      - "application/json"
      responses:
        200:
          description: "successful operation"
          schema:
            type: "array"
            items:
              $ref: "#/definitions/ReplacementLesson"
  /replacement/findByDate:
    get:
      tags:
      - "replacement lessons"
      summary: "Finds replacement lessons by date"
      operationId: "findReplacementLessonsByDate"
      security:
      - passwordAuth: []
      produces: 
      - "application/json"
      parameters:
      - name: "date"
        in: "query"
        description: "Date of the searched replacement lessons"
        type: "string"
        format: "date"
        required: true
      responses:
        200:
          description: "successful operation"
          schema:
            type: "array"
            items:
              $ref: "#/definitions/ReplacementLesson"
        410:
          description: "Date is not or no longer available"
  /replacement/{id}:
    get:
      tags:
      - "replacement lessons"
      summary: "Get replacement lesson by id"
      operationId: "getReplacement"
      security:
      - passwordAuth: []
      produces: 
      - "application/json"
      parameters:
      - name: "id"
        in: "path"
        description: "Replacement lesson's id"
        type: "integer"
        format: "int64"
        required: true
      responses:
        200:
          description: "successful operation"
          schema:
            $ref: "#/definitions/ReplacementLesson"
        404:
          description: "Cannot find a matching replacement lesson"
        410:
          description: "The lesson is no longer available."
  /course/{course}/replacements:
    get:
      tags:
      - "replacement lessons"
      summary: "Get replacement lesson of a course/class"
      operationId: "getReplacementByCourse"
      security:
      - passwordAuth: []
      produces: 
      - "application/json"
      parameters:
      - name: "course"
        in: "path"
        type: "string"
        required: true
      responses:
        200:
          description: "successful operation"
          schema:
            type: "array"
            items:
              $ref: "#/definitions/ReplacementLesson"
  /course/{course}/timetable:
    get:
      tags:
      - "timetable"
      summary: "Returns course's timetable"
      operationId: "getTimetable"
      security:
      - passwordAuth: []
      produces:
      - "application/json"
      parameters:
      - name: "course"
        in: "path"
        type: "string"
        required: true
      responses:
        200:
          description: "Lessons sorted by weekday, period and teacher."
          schema:
            type: "array"
            items:
              $ref: '#/definitions/Lesson'
        404:
          description: "Cannot find the course"
  /course/{course}/exams:
    get:
      tags:
      - "examination scheduling"
      summary: "Returns course's exams"
      operationId: "getExams"
      security:
      - passwordAuth: []
      produces:
      - "application/json"
      parameters:
      - name: "course"
        in: "path"
        type: "string"
        required: true
      responses:
        200:
          description: "Lessons sorted by weekday and period"
          schema:
            type: "array"
            items:
              $ref: '#/definitions/Exam'
        404:
          description: "Cannot find the course"
      
securityDefinitions:
  passwordAuth:
    type: basic
definitions:
  Exam:
    type: "object"
    properties:
      id:
        type: "integer"
        format: "int64"
        x-go-name: "ID"
      date:
        type: "string"
        format: "date"
      startPeriod:
        type: "integer"
        minimum: 1
        maximum: 15
        description: "The period of the day where the exam starts"
      endPeriod:
        type: "integer"
        minimum: 1
        maximum: 15
        description: "The period of the day where the exam ends"
      lesson:
        $ref: '#/definitions/Lesson'
  Lesson:
    type: "object"
    properties:
      weekday:
        type: "integer"
        minimum: 0
        maximum: 7
      period:
        type: "integer"
        minimum: 1
        maximum: 15
        description: "The period of the day where the lesson is"
      course:
        type: "string"
        description: "Class or Course"
      subject:
        $ref: "#/definitions/Subject"
      teacher:
        $ref: "#/definitions/Teacher"
      additionalInformation:
        type: string
        description: "An additional information like 'Every 14 days only'"
      room:
        type: string
  ReplacementLesson:
    type: "object"
    properties:
      id:
        type: "integer"
        format: "int64"
        x-go-name: "ID"
      date:
        type: "string"
        format: "date"
      lesson:
        $ref: '#/definitions/Lesson'
      replacementLesson:
        $ref: '#/definitions/Lesson'
  Subject:
    type: 'object'
    properties:
      abbreviation:
        type: "string"
        description: "The abbreviation of the subject like LB for sports."
      name:
        type: "string"
  Teacher:
    type: "object"
    properties:
      identifier:
        type: "string"
        description: "An unique string that is mostly the abbreviation of the teacher's name"
      name:
        type: "string"
        description: "The family name of the teacher"