Stabilize legacy Steven API endpoints and add OpenAPI spec

steven/API/openapi.yaml

@@ -0,0 +1,527 @@
+openapi: 3.0.3
+info:
+  title: SPOTA Legacy Steven API
+  version: 0.1.0
+  description: |
+    Dokumentasi awal endpoint legacy di `steven/API`.
+    Fokus dokumen ini adalah endpoint yang sudah distabilkan dan masih dipakai integrasi lama.
+servers:
+  - url: https://spota.informatika.untan.ac.id/steven/API
+security:
+  - LegacySecretQuery: []
+  - LegacySecretHeader: []
+tags:
+  - name: Robot
+    description: Endpoint machine-to-machine dengan secret legacy.
+  - name: Session
+    description: Endpoint yang memerlukan session login aplikasi.
+paths:
+  /getListMahasiswa.php:
+    get:
+      tags: [Robot]
+      summary: Ambil daftar mahasiswa
+      parameters:
+        - $ref: '#/components/parameters/SecretQuery'
+        - name: mulaiTahun
+          in: query
+          schema:
+            type: integer
+          description: Filter angkatan minimal.
+        - name: withHP
+          in: query
+          schema:
+            type: string
+          description: Jika ada, sertakan `hp` dan `hpOrtu`.
+      responses:
+        '200':
+          description: Data mahasiswa
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ListMahasiswaResponse'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+  /getListDosen.php:
+    get:
+      tags: [Robot]
+      summary: Ambil daftar dosen
+      parameters:
+        - $ref: '#/components/parameters/SecretQuery'
+      responses:
+        '200':
+          description: Data dosen
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ListDosenResponse'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+  /getListTugasAkhir.php:
+    get:
+      tags: [Robot]
+      summary: Ambil daftar tugas akhir mahasiswa
+      parameters:
+        - $ref: '#/components/parameters/SecretQuery'
+        - name: mulaiTahun
+          in: query
+          schema:
+            type: integer
+        - name: withoutKep
+          in: query
+          schema:
+            type: string
+          description: Jika ada, data tidak difilter `kep_akhir = 1`.
+      responses:
+        '200':
+          description: Data tugas akhir
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ListTugasAkhirResponse'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+  /getListDataTAMahasiswa.php:
+    get:
+      tags: [Robot]
+      summary: Ambil data rekap tugas akhir beserta jadwal
+      parameters:
+        - $ref: '#/components/parameters/SecretQuery'
+      responses:
+        '200':
+          description: Data TA mahasiswa
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ListDataTaMahasiswaResponse'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+  /getDetailTugasAkhirMahasiswa.php:
+    get:
+      tags: [Robot]
+      summary: Ambil detail tugas akhir mahasiswa
+      parameters:
+        - $ref: '#/components/parameters/SecretQuery'
+        - name: id
+          in: query
+          required: true
+          schema:
+            type: integer
+      responses:
+        '200':
+          description: Detail tugas akhir
+          content:
+            application/json:
+              schema:
+                type: object
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+  /getListKK.php:
+    get:
+      tags: [Robot]
+      summary: Ambil daftar kelompok keahlian
+      parameters:
+        - $ref: '#/components/parameters/SecretQuery'
+      responses:
+        '200':
+          description: Data kelompok keahlian
+          content:
+            application/json:
+              schema:
+                type: object
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+  /sendMail.php:
+    post:
+      tags: [Robot]
+      summary: Kirim email HTML ke banyak penerima
+      requestBody:
+        required: true
+        content:
+          application/x-www-form-urlencoded:
+            schema:
+              type: object
+              required: [secret, to, judul, content]
+              properties:
+                secret:
+                  type: string
+                to:
+                  type: string
+                  description: JSON array string email penerima.
+                  example: '["user1@example.com","user2@example.com"]'
+                judul:
+                  type: string
+                content:
+                  type: string
+                from:
+                  type: string
+      responses:
+        '200':
+          description: Email terkirim
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/StandardSuccess'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '422':
+          $ref: '#/components/responses/ValidationError'
+  /willy_manageJadwal.php:
+    post:
+      tags: [Robot]
+      summary: Tambah, ubah, atau hapus jadwal sidang
+      security:
+        - LegacySecretHeader: []
+        - LegacySecretQuery: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              oneOf:
+                - $ref: '#/components/schemas/ManageJadwalAddRequest'
+                - $ref: '#/components/schemas/ManageJadwalUpdateRequest'
+                - $ref: '#/components/schemas/ManageJadwalDeleteRequest'
+      responses:
+        '200':
+          description: Operasi jadwal berhasil
+          content:
+            application/json:
+              schema:
+                type: object
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '422':
+          $ref: '#/components/responses/ValidationError'
+  /getBerkasSidangMahasiswa.php:
+    get:
+      tags: [Session]
+      summary: Ambil daftar berkas sidang mahasiswa
+      description: |
+        Default untuk mahasiswa yang sedang login.
+        Jika memakai `bypassSaya`, akses hanya untuk dosen terkait atau admin.
+      security: []
+      parameters:
+        - name: idRekapHasil
+          in: query
+          required: true
+          schema:
+            type: integer
+        - name: jenis
+          in: query
+          required: true
+          schema:
+            type: string
+            enum: [Outline, SidHas, Sidang]
+        - name: bypassSaya
+          in: query
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Berkas sidang
+          content:
+            application/json:
+              schema:
+                type: object
+        '403':
+          description: Forbidden
+  /verifBerkasAdmin.php:
+    post:
+      tags: [Session]
+      summary: Verifikasi berkas oleh admin
+      security: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+      responses:
+        '200':
+          description: Verifikasi tersimpan
+        '403':
+          description: Forbidden
+  /verifBerkasDosen.php:
+    post:
+      tags: [Session]
+      summary: Verifikasi berkas oleh dosen terkait
+      security: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+      responses:
+        '200':
+          description: Verifikasi tersimpan
+        '403':
+          description: Forbidden
+components:
+  securitySchemes:
+    LegacySecretQuery:
+      type: apiKey
+      in: query
+      name: secret
+    LegacySecretHeader:
+      type: apiKey
+      in: header
+      name: X-API-Key
+  parameters:
+    SecretQuery:
+      name: secret
+      in: query
+      required: true
+      schema:
+        type: string
+  responses:
+    Unauthorized:
+      description: Secret salah atau tidak dikirim.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ErrorResponse'
+    ValidationError:
+      description: Parameter tidak lengkap atau tidak valid.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ErrorResponse'
+  schemas:
+    StandardSuccess:
+      type: object
+      properties:
+        status:
+          oneOf:
+            - type: integer
+            - type: boolean
+        msg:
+          type: string
+    ErrorResponse:
+      type: object
+      properties:
+        status:
+          oneOf:
+            - type: integer
+            - type: boolean
+        msg:
+          type: string
+    MahasiswaItem:
+      type: object
+      properties:
+        id:
+          type: integer
+        nim:
+          type: string
+        nama:
+          type: string
+        email:
+          type: string
+        urlFoto:
+          type: string
+        angkatan:
+          type: integer
+        hp:
+          type: string
+        hpOrtu:
+          type: string
+    ListMahasiswaResponse:
+      type: object
+      properties:
+        status:
+          type: integer
+        msg:
+          type: string
+        data:
+          type: array
+          items:
+            $ref: '#/components/schemas/MahasiswaItem'
+    DosenItem:
+      type: object
+      properties:
+        id:
+          type: integer
+        nip:
+          type: string
+        nama:
+          type: string
+        email:
+          type: string
+        hp:
+          type: string
+        urlFoto:
+          type: string
+    ListDosenResponse:
+      type: object
+      properties:
+        status:
+          type: integer
+        msg:
+          type: string
+        data:
+          type: array
+          items:
+            $ref: '#/components/schemas/DosenItem'
+    TugasAkhirItem:
+      type: object
+      properties:
+        id:
+          type: integer
+        judul:
+          type: string
+        nim:
+          type: string
+        nama:
+          type: string
+        pemb1:
+          type: string
+        pemb2:
+          type: string
+        peng1:
+          type: string
+        peng2:
+          type: string
+        semester:
+          type: string
+        tahun:
+          type: string
+        tanggalKeputusan:
+          type: string
+        waktuKeputusan:
+          type: string
+        idPraoutline:
+          type: integer
+        keputusan:
+          type: string
+        sidang:
+          type: integer
+    ListTugasAkhirResponse:
+      type: object
+      properties:
+        status:
+          type: integer
+        msg:
+          type: string
+        data:
+          type: array
+          items:
+            $ref: '#/components/schemas/TugasAkhirItem'
+    JadwalItem:
+      type: object
+      properties:
+        jenis:
+          type: string
+        waktu:
+          type: string
+        ruangan:
+          type: string
+    DataTaMahasiswaItem:
+      type: object
+      properties:
+        id:
+          type: integer
+        judul:
+          type: string
+        nim:
+          type: string
+        pemb1:
+          type: string
+        pemb2:
+          type: string
+        peng1:
+          type: string
+        peng2:
+          type: string
+        semester:
+          type: string
+        tahun:
+          type: string
+        tanggalKeputusan:
+          type: string
+        waktuKeputusan:
+          type: string
+        kelompokKeahlian:
+          type: string
+        jadwal:
+          type: array
+          items:
+            $ref: '#/components/schemas/JadwalItem'
+    ListDataTaMahasiswaResponse:
+      type: object
+      properties:
+        status:
+          type: integer
+        data:
+          type: array
+          items:
+            $ref: '#/components/schemas/DataTaMahasiswaItem'
+    ManageJadwalBaseRequest:
+      type: object
+      required:
+        - act
+        - nim
+        - judul
+        - ruangan
+        - jenis
+        - waktuSidang
+        - namaPemb1
+        - namaPemb2
+        - namaPeng1
+        - namaPeng2
+      properties:
+        act:
+          type: string
+        secret:
+          type: string
+        nim:
+          type: string
+        judul:
+          type: string
+        ruangan:
+          type: string
+        jenis:
+          type: string
+          enum: [Outline, SidHas, Sidang]
+        waktuSidang:
+          type: string
+          example: '2026-05-07 08:00:00'
+        namaPemb1:
+          type: string
+        namaPemb2:
+          type: string
+        namaPeng1:
+          type: string
+        namaPeng2:
+          type: string
+    ManageJadwalAddRequest:
+      allOf:
+        - $ref: '#/components/schemas/ManageJadwalBaseRequest'
+        - type: object
+          properties:
+            act:
+              type: string
+              enum: [add]
+    ManageJadwalUpdateRequest:
+      allOf:
+        - $ref: '#/components/schemas/ManageJadwalBaseRequest'
+        - type: object
+          required: [id]
+          properties:
+            act:
+              type: string
+              enum: [update]
+            id:
+              type: integer
+    ManageJadwalDeleteRequest:
+      type: object
+      required: [act, secret, id, nim]
+      properties:
+        act:
+          type: string
+          enum: [delete]
+        secret:
+          type: string
+        id:
+          type: integer
+        nim:
+          type: string