feat: API implementation and Docker artifact publishing

[davidgamez]

Description

This PR adds the first stable implementation of the OpenAPI schema. The implementation uses the https://github.com/openapitools/openapi-generator Maven plugin to generate most of the code and interfaces. The core validator functionality is located in the official GTFS validator repository.

Out of scope

• API Deployment to a MobilityData environment. This will not be residing in the repository. This repository will serve as a generic, simple API interface for the official GTFS validator.
• API support of unreleased GTFS validator functionality. While we consider this an interesting case, it should be addressed in a follow-up PR; this PR is complete and heavy enough to review.

From our AI friend

This pull request introduces the initial setup for the GTFS Validator API project, providing a production-ready, containerized, and CI-integrated Spring Boot HTTP API for the MobilityData Canonical GTFS Schedule Validator. The changes establish the build system, code formatting, Dockerization, continuous integration workflows, and detailed documentation, as well as the application entry point.

The most important changes are:

Build System and Dependency Management

• Added a comprehensive pom.xml configuring the project as a Spring Boot application, managing dependencies (including the validator core and patched transitive dependencies), plugins for OpenAPI code generation, code formatting (Spotless with google-java-format), and resource handling. The build also integrates the OpenAPI spec and sets up code style enforcement.

Dockerization

• Introduced a multi-stage Dockerfile to build and package the application as a minimal, production-ready container image, running as a non-root user and exposing configuration via JAVA_OPTS.
• Added a .dockerignore file to exclude unnecessary files and directories from Docker build context, improving build efficiency and security.

Continuous Integration

• Added GitHub Actions workflow .github/workflows/build.yml for building, testing, and enforcing code style on every push, pull request, or manual trigger.
• Added .github/workflows/docker.yml workflow to build and publish multi-arch Docker images to GitHub Container Registry on pushes, tags, releases, and pull requests.

OpenAPI Code Generation

• Added .openapi-generator-ignore to prevent overwriting custom source files during OpenAPI code generation, ensuring maintainability of hand-written code.

Documentation and Entry Point

• Created a detailed README.md describing the project, endpoints, build/test instructions, Docker usage, CI/CD processes, configuration, and project structure.
• Added the main application entry point in src/main/java/org/mobilitydata/gtfsvalidator/api/Application.java for the Spring Boot service.

[jcpitre]

I am not sure the ValidationRunner is completely thread safe.

[davidgamez]

This uses the same pattern as the current API => https://github.com/MobilityData/gtfs-validator/blob/87109ed0858fbad23ccf47bb5925cd3ea38acf99/web/service/src/main/java/org/mobilitydata/gtfsvalidator/web/service/Main.java#L32

[jcpitre]

I guess in that case the current API is wrong. Or the number of simultaneous requests is limited to 1? Not sure.
See ValidationRunner.run for a non thread safe operation.
It's not catastrophic if it fails, just that the memory info int he report could be wrong.

[davidgamez]

Let's fix it then. I see that the memory reporting is impacted, not the validation output. In the current MD deployment, we don't have concurrent calls; that's why there is no impact on the memory reports.

[jcpitre]

It can be fixed or documented that the number of concurrent requests should not be more than 1, like in the current web validator.
But fixing is safer.

[davidgamez]

Created GTFS issue and added a comment in the code.

[jcpitre]

LGTM!

[themightychris]

Thanks for building this out, @davidgamez — a synchronous validator service is exactly what we need.

Use case: we're integrating the canonical validator into an automated GTFS pipeline. Each run validates its input and output feeds, and a single upstream feed update can fan out to several runs at once. We'd rather keep one warm instance that absorbs occasional concurrent validations than scale to zero (cold starts) or serialize — so concurrent correctness matters to us.

While test-driving this PR's image we ran into the memory-report thread-safety bug you filed as #2168, so I opened a fix upstream: MobilityData/gtfs-validator#2169 (thread-confine MemoryUsageRegister — ~3 lines + a deterministic test).

Measured with this PR's image, one shared ValidationRunner, 8 concurrent validations of a ~3 MB / ~13k-trip feed:

• Current core: summary.memoryUsageRecords is corrupted under concurrency — the 8 runs reported 4 / 13 / 14 / 17 / 24 / 28 / 28 / 31 / 32 records (single-run baseline is 4). Validation notices were unaffected (the NoticeContainer is per-run).
• With #2169: all 8 runs report exactly 4 records, no cross-run contamination; notices identical.
• Resource use is comfortably under-linear with concurrency — 8 concurrent peaked around 1.7 GB RSS / 1.2 GB heap and ~4.75 cores on a multi-core host — so a single warm instance handles bursts well, with CPU the practical limit before memory.

Happy to follow up with backpressure (the OpenAPI already advertises 429 / maxRequestsPerMinute) and a documented heap-default JAVA_OPTS if those would be welcome.

[davidgamez]

Thanks for building this out, @davidgamez — a synchronous validator service is exactly what we need.

Amazing! I'm merging this now and will take a look at MobilityData/gtfs-validator#2169 shortly