Faculty APIs

[gerardomaruotti]

Branch guide (feature/faculty-api vs master)

High-level changes

• Spec upgraded from OpenAPI 3.0.3 to 3.1.1 and API version bumped 2.2.3 → 2.2.4.
• Monolithic openapi.yaml removed from version control and replaced by a multi-file source tree under src/; bundled file is now generated locally and gitignored.
• Paths expanded from 77 to 109 endpoints (+32), adding an entire faculty surface, place booking APIs, emergency/fault reporting, and richer course/lecture resources. /v2/courses is superseded by /courses; /departments is removed.
• Tags are grouped into Common/Students/Faculty with x-tagGroups to improve Swagger UI navigation.

Repository structure (new vs master)

• src/index.yaml is the entry point that bundles all paths/components; it enumerates every path via $ref.
• src/paths/ now holds consumer-specific trees:
  • common/: auth, profile (me/deadlines/messages/notifications/preferences), news, places (/v2/places plus new /v2/places/bookings upsert/fetch), emergencies, faults, people, bookings, courses (including nested lectures/notices/files/assignments/videolectures), guides.
  • students/: auth career switch, student profile, exams (booking/reschedule), lectures feed, ESC, tickets (topics/FAQ/thread CRUD), job offers, offering, surveys.
  • faculty/: profile (self update, publications), exams (list/detail/notify/add student), courses (list students/collaborators, message students), digital signature flows (documents, sessions, OTP verify/sign), calendar (calendars/events CRUD and materials).
• src/components/ split by concern:
  • schemas/common.yaml: shared domain (auth/login, bookings, places, emergency, faults, news, people, notifications, course material, place booking upsert, errors, etc.).
  • schemas/students.yaml: student-facing models (student profile, grades/provisional grades, deadlines, lectures, virtual classrooms, tickets, job offers, offering, surveys).
  • schemas/faculty.yaml: faculty models (course students/collaborators, course lectures/notices/materials, exams/enrollments, calendar/event/materials, publications, signing session/documents/OTP).
  • responses.yaml: standardized errors plus signing-specific responses (invalid OTP, session expired, too many attempts, precondition failed).
  • parameters.yaml: reusable path/query/header params (course/exam/student IDs, pagination, place filters, signing session/document IDs, fault ID, etc.).
  • security-schemes.yaml: bearerAuth definition.
• Generated outputs are intentionally ignored: openapi.yaml, node_modules/, typescript-fetch-client/, .openapi-generator/, with .openapi-generator-ignore trimming generator artifacts (tests, git metadata).

Tooling and scripts introduced

• New package.json (tracked) with npm scripts:
  • bundle: swagger-cli bundle src/index.yaml -o openapi.yaml -t yaml.
  • validate: swagger-cli validate openapi.yaml.
  • bundle:verify: runs bundle then validate.
  • generate:client: bundles and runs openapi-generator-cli (typescript-fetch, version 7.4.0, package name @polito/api-client, version 1.0.0) into typescript-fetch-client/.
  • generate:client:fix: runs client generation then fix:client.
  • fix:client: prepends // @ts-nocheck to the generated runtime and (conditionally) FeatureAllOfId.ts to work around generator typings.
• openapitools.json pins the generator CLI schema/version (7.4.0) for reproducible client builds.
• package-lock.json added for the Node toolchain (swagger-cli, @openapitools/openapi-generator-cli).

CI/CD updates

• New workflow .github/workflows/validate-openapi.yml runs on PRs to master: checkout, Node 18 setup, npm ci, npm run bundle, npm run validate, install global openapi-generator-cli, and validate the bundle again.
• Existing client publish workflow now installs Node 18 dependencies and bundles the spec before invoking the generator, then configures the npm registry via npm config set registry (instead of registry-url in setup-node).

API surface delta highlights

• Common: added /emergencies (+contacts/detail) and /faults CRUD; extended places with /v2/places/bookings upsert/fetch and location filters; course resources gain lecture-detail routes and notice IDs.
• Students: core student/exam/ticket/lecture/offering/job-offer/survey routes preserved; now share common schemas and paths pulled under the new tag grouping.
• Faculty: entirely new surface for profile (/faculty/me + publications), exams (list/detail/notify/add student), courses (list/enroll students, manage collaborators, message class), digital signature (documents/sessions/OTP verification/sign), and calendar (calendars/events CRUD, materials).
• Removed: /departments endpoint; /v2/courses replaced by /courses equivalents.

Working with the branch

• Generate and validate locally with npm run bundle:verify; the bundle stays in openapi.yaml (gitignored) for tooling or mock servers.
• Regenerate the TypeScript Fetch client with npm run generate:client:fix if you need SDK updates (keeps // @ts-nocheck patch applied).
• Use docker-compose up to preview the bundled spec in swagger-ui on port 8080.