feat: operation api OpenAPI sync with Mobility Database Catalog API

[davidgamez]

Summary:

Fixes #1151

This PR is a significant change in the operations API architecture. As of now, the operations API is an "independent" API with similar behaviour to the public API. This makes it harder to maintain, as most of the converters/transformers(we called them models) were duplicated. Porting functionality to the operations API always implied duplicate efforts. To solve this, we are now copying all the OpenAPI entities from the public API to the operations API. On the implementation side, we are inheriting the models from the public API and adding extra fields and logic. At the OpenAPI level, we keep separate sets of paths and' params' to allow having different end-user interfaces while reusing the entities and implementation.

Endpoints changes and additions:

• /v1/operations/feeds(modified): This endpoint only returns feed general information without any data type. Before, if data_type was provided, it returned general feed information along with data_type-specific information.
• /v1/operations/gtfs_feeds/{id}(new): This endpoint returns GTFS feed information
• /v1/operations/gtfs_rt_feeds/{id}(new): This endpoint returns GTFS-RT feed information

OpenApi changes

How to keep the public API and the operations API components in sync?

• Make sure that new entities only applicable to the Operations API are marked with the x-operation: true tag. Ideally, it should be marked with x-internal: true, but due to this bug, we can't. Example:

    OperationFeed:
      x-operation: true
      allOf:
        - $ref: "#/components/schemas/BasicFeed"
        - type: object
          description: Feed response model.

• Execute the script ./api-operations-update-schema.sh. This script will keep in the OperationsAPI yaml file only the components marked with the x-operations tag and copy all components from the Mobility Database Catalog API.

From our AI friend:

This pull request introduces significant refactoring and modernization of the Mobility Feed API codebase, with a focus on replacing legacy generated code (feeds_operations_gen) with new generated code (feeds_gen), improving error handling, and clarifying project architecture and development workflows. The changes also enhance test reliability and update code references for better maintainability.

Project architecture and documentation:

• Added a comprehensive project architecture and workflow guide in .github/copilot-instructions.md, detailing code generation patterns, critical development commands, error handling, database conventions, and integration points.

Code generation and project structure refactor:

• Replaced all references to legacy generated code (feeds_operations_gen) with new generated code (feeds_gen) across the operations API, including imports, .gitignore, .coveragerc, and OpenAPI generator file lists. This unifies the codebase around the new spec-first API implementation. [1] [2] [3] [4]
• Updated the function configuration to include the db_models folder for shared models, supporting the new code structure.

API implementation and query logic improvements:

• Refactored the main API implementation (feeds_operations_impl.py) to use the new models from feeds_gen, replaced the legacy feed processing logic with a unified OperationFeedImpl.from_orm, and added new endpoints for fetching individual GTFS and GTFS-RT feeds. [1] [2] [3] [4]
• Improved query helper logic to accept a model parameter directly, removed hardcoded model selection, and clarified query logging. [1] [2]

Error handling and reliability:

• Enhanced error handling in feed ORM conversion to avoid exceptions on missing related objects by using conditional list comprehensions.
• Improved database error handling tests by mocking external dependencies for more reliable test coverage.

Cleanup and dependency updates:

• Removed obsolete base feed implementation code (basic_feed_impl.py) as part of the migration to new models.
• Updated references to the compare_java_versions utility to the new location for consistency. [1] [2] [3]
• Added pycountry to requirements for enhanced data handling.
• Updated .flake8 exclusions to match new generated code folder names.

These changes collectively modernize the codebase, improve maintainability, and clarify development practices for current and future contributors.
Expected behavior:

Explain and/or show screenshots for how you expect the pull request to work in your testing (in case other devices exhibit different behavior).

Testing tips:

Provide tips, procedures and sample files on how to test the feature.
Testers are invited to follow the tips AND to try anything they deem relevant outside the bounds of the testing tips.

Please make sure these boxes are checked before submitting your pull request - thanks!

• Run the unit tests with ./scripts/api-tests.sh to make sure you didn't break anything
• Add or update any needed documentation to the repo
• Format the title like "feat: [new feature short description]". Title must follow the Conventional Commit Specification(https://www.conventionalcommits.org/en/v1.0.0/).
• Linked all relevant issues
• Include screenshot(s) showing how this pull request works and fixes the issue(s)

[davidgamez]

This file adds context to copilot and other AI agents.

[davidgamez]

I had to add this patch because the test started failing locally; in fact, I'm not sure why it was working in the first place...