Update OpenAPI specs to match current implementation; split into frontend and integration surfaces with operation-level shared components

[Copilot]

The single rest.yaml spec had diverged significantly from the codebase — missing entire endpoint groups, incorrect paths, wrong schema fields, and no coverage of the integration API surface.

shared.yaml — Single source of truth — new file

• Contains all 37 schemas under components.schemas (read DTOs, write DTOs, auth, user, API key, import/export, error/validation)
• Contains all 47 operation definitions under components.x-operations — every GET, POST, PUT, and DELETE for every endpoint in the API, fully defined with responses, parameters, and requestBody
• Both security schemes: bearerAuth (JWT) and apiKeyAuth (X-Api-Key header)
• 8 reusable path parameters (levelId, groupId, teacherId, unitId, roomId, scheduleItemId, userId, apiKeyId)
• 2 reusable responses (Unauthorized, Forbidden)
• Public endpoints explicitly declare security: []
• No top-level paths, servers, or global security

rest.yaml — Frontend API (/api/v1)

• servers: [{url: /api/v1}] — base path modeled in servers, not in path prefixes
• Global security: [{bearerAuth: []}]
• Paths compose HTTP methods by $ref-ing operations from shared.yaml:

  /rooms:
    get:
      $ref: 'shared.yaml#/components/x-operations/listRooms'
    post:
      $ref: 'shared.yaml#/components/x-operations/createRoom'

• Zero local schemas or inline operations — all definitions live in shared.yaml
• Full endpoint coverage: Auth (login/logout/refresh/me/password), Users (CRUD), API Keys (CRUD), Levels, Groups, Teachers, Teaching Units, Rooms, Schedule (CRUD + batch), Export, Import
• Fixed schedule paths: /levels/{levelId}/schedule → /schedule (matches actual ScheduleController mapping)
• Fixed response types: GET /levels returns LevelDetailsDTO[], not LevelDTO[]
• Fixed schemas: added missing type/classe fields to Group DTOs, corrected abbreviation as required, type: number → type: integer, format: int64 for all IDs/sizes

integration.yaml — Integration API (/integration) — new file

• servers: [{url: /integration}]
• Global security: [{apiKeyAuth: []}]
• Read-only (GET only) — 14 paths referencing the same shared operations
• Excludes users and API key management endpoints
• Zero local schemas or inline operations

Validity

• All $ref sibling violations fixed (TeachingUnitDTO.level uses allOf wrapper)
• YAML validated, all $ref links resolve, no duplicate keys or operationIds
• No endpoint contracts or behavior changed

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Update OpenAPI Specification to Match Current Implementation</issue_title>
<issue_description>The OpenAPI specification file (src/main/resources/api/rest.yml) has diverged from the actual implementation due to recent codebase changes. This has created inconsistencies between the documented API and the real endpoints, request/response formats, and error codes.

Action items:

• Review the latest Java backend implementation against the endpoints documented in the OpenAPI specification.
• Identify discrepancies and outdated details in rest.yml.
• Update the OpenAPI spec to accurately reflect the current API, including request/response bodies, parameters, and expected status codes.
• Ensure the documentation remains aligned with future code changes.

This update will help developers and integrators rely on the OpenAPI spec for client generation and system integration.

Files involved:

• src/main/resources/api/rest.yml</issue_description>

<agent_instructions>I want to maintain OpenAPI documentation manually as YAML files and keep them as the source of truth. I do NOT want to generate docs from code annotations or modify application code for documentation purposes.

The API has evolved and now consists of two distinct surfaces:

1. Frontend API

   • Base path: /api/v1/**
   • Authentication: JWT Bearer token (Authorization: Bearer <token>)
   • Full feature set, including write operations and user-related endpoints.

2. Integration API

   • Base path: /integration/**
   • Authentication: custom header X-Api-Key
   • Read-only (GET only)
   • Subset of the frontend API endpoints
   • Excludes endpoints related to users and API key management.

I already have older OpenAPI YAML files that are partially outdated. I want help updating and structuring them correctly.

Requirements for the YAML design:

• Keep two separate OpenAPI specs, one per API surface.

• Avoid duplication where possible while keeping specs clear for consumers.

• Properly define security schemes for each API.

• Clearly document constraints such as:

  • allowed HTTP methods
  • authentication rules
  • endpoint availability differences

• Include good descriptions, tags, and structure so that the documentation is professional and understandable to other developers.

• Follow OpenAPI best practices for naming, organization, and reusability (components, schemas, responses, parameters).

• Do not assume code annotations or runtime generation — everything must be expressible in YAML.

What I want from you:

• Write the yml files
• Make the specs maintainable long-term</agent_instructions>

Comments on the Issue (you are @copilot in this section)

• Fixes Update OpenAPI Specification to Match Current Implementation #31

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[rivon0507]

@copilot

Continue working with the existing OpenAPI specifications.

There are currently two spec files:

• Frontend API spec
• Integration API spec

Do not merge them or change their roles.

---

Task

Introduce a shared specification file to centralize reusable definitions and reduce duplication, and correctly model base paths using OpenAPI servers.

---

Requirements

1. Create a shared file

Create a new OpenAPI YAML file that contains only reusable definitions:

• components.schemas
• components.securitySchemes
• reusable path definitions (for example components.pathItems)

Do not include:

• info
• servers
• top-level paths
• global security

---

2. Move shared elements

Move all reusable elements common to both specs into the shared file:

• schemas
• shared path structures
• security schemes

---

3. Update the two existing specs

They must:

• reference shared paths from the shared file instead of defining them inline

• reference their global security scheme from the shared file

• keep their own:

  • info
  • servers
  • security
  • path selection

---

4. Base path handling (important)

Currently the API prefixes are only mentioned in descriptions. Fix this.

Move base paths into the servers section:

• Frontend spec server URL must include /api/v1
• Integration spec server URL must include /integration

Paths themselves must not contain these prefixes.

---

5. Security rules

• Each spec must define its own global security.

• Shared paths must not be duplicated solely because authentication differs.

• Public endpoints must explicitly declare:

  security: []
  

---

6. Integration spec constraints

• Must remain a strict subset of frontend endpoints.
• Must contain only GET operations.
• Must not redefine shared structures.

---

7. Validity constraints

• YAML must be valid.
• OpenAPI must be valid.
• No duplicate keys.
• $ref must not appear with sibling fields.
• Do not change endpoint contracts or behavior.

---

Output format

Return:

1. the new shared file
2. modified sections of frontend spec
3. modified sections of integration spec

[Copilot]

@copilot

Continue working with the existing OpenAPI specifications....

Done in 556ebf2 and da21063.

Changes made:

1. Created shared.yaml — contains all centralized reusable definitions:

   • components.schemas — 8 shared response schemas (LevelDTO, GroupDTO, TeacherDTO, etc.)
   • components.securitySchemes — both bearerAuth (JWT) and apiKeyAuth (X-Api-Key)
   • components.parameters — 6 shared path parameters
   • components.responses — Unauthorized
   • components.pathItems — 14 shared GET path items used by both surfaces

2. Updated rest.yaml — references shared components via $ref: 'shared.yaml#/...', adds global security: [{bearerAuth: []}], public endpoints use security: []. GET-only shared paths (/rooms/available, /levels/{levelId}/teachingUnits) use $ref to shared pathItems. Multi-method paths are defined inline since $ref can't have siblings. Frontend-only schemas, params, and responses remain local.

3. Updated integration.yaml — reduced to ~80 lines. All 14 paths $ref shared pathItems, security scheme references shared.yaml. Zero duplicated definitions.

All $ref sibling violations fixed (TeachingUnitDTO.level uses allOf wrapper). Base paths are in servers only. YAML validated, build passes.

[rivon0507]

@copilot

Continue refining the existing OpenAPI specifications.

Change the refactoring approach: do not share full paths between files. Instead, centralize operation definitions and have each spec compose its paths from those shared operations.

Goal

Make shared.yaml the single source of truth for all operation logic, schemas, and security schemes.

---

Required structure

shared.yaml

Must contain:

• all components.schemas
• all components.securitySchemes
• a reusable operations container under components (for example components.x-operations)
• inside that container: every operation definition (get, post, etc.) for every endpoint in the API

Each operation must be fully defined (responses, parameters, requestBody, etc.).

If an endpoint is public, that operation must explicitly declare:

security: []

Do not define top-level paths here.

---

rest.yaml (frontend spec)

Must:

• keep its own openapi, info, servers, and global security
• define servers: - url: /api/v1
• define its paths normally, but each HTTP method must $ref the operation from shared.yaml
• not define schemas locally
• not define operations inline

Example pattern:

paths:
  /rooms:
    get:
      $ref: 'shared.yaml#/components/x-operations/listRooms'
    post:
      $ref: 'shared.yaml#/components/x-operations/createRoom'

---

integration.yaml (integration spec)

Must:

• keep its own openapi, info, servers, and global security
• define servers: - url: /integration
• define paths that reference only the subset of operations it exposes
• include only GET operations
• not define schemas locally
• not define operations inline

---

Rules

• Do not change endpoint behavior or contracts.

• Do not rename schemas or endpoints.

• Do not duplicate operations.

• Do not inline operations in rest.yaml or integration.yaml.

• YAML and OpenAPI must remain valid:

  • no duplicate keys
  • $ref must not have sibling fields

---

Output

Return full contents of:

• shared.yaml
• rest.yaml
• integration.yaml

Include short inline comments explaining structural decisions.

[Copilot]

@copilot

Continue refining the existing OpenAPI specifications....

Done in d799ef0.

Structure:

• shared.yaml — single source of truth:

  • 37 schemas under components.schemas
  • 47 fully-defined operations under components.x-operations
  • Both security schemes, 8 parameters, 2 responses
  • No top-level paths, servers, or global security
  • Public endpoints explicitly declare security: []

• rest.yaml (~170 lines) — composes paths from shared operations:

  /rooms:
    get:
      $ref: 'shared.yaml#/components/x-operations/listRooms'
    post:
      $ref: 'shared.yaml#/components/x-operations/createRoom'

  No local schemas, no inline operations. servers: [{url: /api/v1}].

• integration.yaml (~100 lines) — GET-only subset, same pattern:

  /rooms:
    get:
      $ref: 'shared.yaml#/components/x-operations/listRooms'

  No local schemas, no inline operations. servers: [{url: /integration}].