docs: update OpenAPI spec for Infobus API #26

[raguerobermudez]

This PR updates the OpenAPI specification in datahub.yml. The specification now includes the necessary endpoints for data consumption by external services.

GTFS Schedule & Real-Time Endpoints

The specification now provides full coverage for both static and live transit data:

• GTFS Schedule: Documented standard tables, including providers, agencies, routes, and stops.

• GTFS Real-Time (RT): Enriched schemas for core live endpoints:

  • next_trips and next_stops: Arrival predictions and ETAs.
  • trip_updates: Real-time status of active trips.
  • vehicle_positions: Live geographic coordinates of the fleet.
  • service_alerts: Communication of service disruptions and detours.

External & Complementary Endpoints

The API scope has been expanded to include external data modules:

• User Reports: Enabled the POST /user-reports endpoint to receive incident data from users and agents.
• Weather: Standardized weather condition reporting.
• Social & Wide Alerts: Added specifications for social media integration and system-wide emergency broadcasts.

Standardization & Architecture

• Component-Based Design: Migrated inline definitions to components/schemas and components/parameters to ensure consistency and reusability.
• Pagination & Filtering: Added global support for limit, offset, and ordering parameters across all collection endpoints.
• Enhanced Metadata: Included fields such as occupancy_status, confidence levels, and data source to provide higher data granularity.

Privacy & Security (Privacy by Design)

• Personal Data Protection In compliance with privacy requirements, the user_name and user_email fields in user_reports have been marked as deprecated and optional to prioritize user anonymity.
• Security Schemes: Defined ApiKeyAuth (header-based) and BearerAuth.
• Write Protection: All POST methods (write operations) now strictly require an API Key to prevent unauthorized data injection or spam.

[Copilot]

Copilot wasn't able to review any files in this pull request.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.