[graduta]

I have a JIRA ticket

• branch and/or PR name(s) include(s) JIRA ID
• issue has "Fix version" assigned
• issue "Status" is set to "In review"
• PR labels are selected

Part of a stack of PRs documenting the HTTP API (O2B-1623). The earlier PRs of the stack are merged: this one is rebased on main and regenerated with the current generator. The following PRs of the stack are rebased one by one, once the previous one is merged.

Notable changes for users:

• filter[lhcPeriodIds][] and filter[dataPassIds][] of GET /api/simulationPasses now reject (400) a value that is not a number, instead of answering with an empty list (the ids given in the query are converted to numbers).
• GET /api/simulationPasses/{id} now rejects (400) an id that is not a positive integer (0, negative numbers, decimals), instead of answering with a 404.
• The simulation passes endpoints are now documented at /api-docs, with parameters, responses and curl examples:
  • GET /api/simulationPasses: paginated list with filters (ids, names, LHC periods, data passes) and sorting
  • GET /api/simulationPasses/{id}: one simulation pass

Notable changes for developers:

• Checked the chain of the endpoint: all files have their license header, no use case is involved, the entity has no createdAt / updatedAt, and the router references existing handlers.
• SimulationPassService.getAll queried the repository directly (with two inline sub-queries) while getByIdentifier and getOneOrFail use small functions: it now uses getAllSimulationPasses(qbConfiguration), getSimulationPassIdsByLhcPeriods and getSimulationPassIdsByDataPasses (each id returned once). The behaviour is unchanged and the three functions have tests. The other counted lists (DataPassService, LhcPeriodStatisticsService, LogService, QcFlagTypeService) still query the repository directly and could follow the same pattern.
• The id of the endpoint is validated with EntityIdDto (it was a plain Joi.number()), with an API test of the four kinds of invalid values.
• The lhcPeriodIds and dataPassIds filters are validated as numbers (they were strings, whereas the ids are integers in the database and the ids filter of the same endpoint, RunFilterDto and the data passes endpoint use numbers). An API test checks the three id filters.
• The two handlers disabled the JSDoc rules: they are documented.
• The pagination components (PageLimit, PageOffset, PageMeta) are added to the spec, as this is the first paginated endpoint documented.
• lib/server/api-docs/openapi.yaml is updated by hand, API.md and index.html are regenerated with npm run docs:api (separate commit).
• List filters are documented as repeated filter[x][] parameters, which is what the Joi validation requires (a single value without [] is rejected). Adds the shared SortOrder schema.

Changes made to the database:

• None

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 46.45%. Comparing base (63833ec) to head (06fe873).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2270      +/-   ##
==========================================
+ Coverage   46.39%   46.45%   +0.05%     
==========================================
  Files        1051     1054       +3     
  Lines       17363    17379      +16     
  Branches     3161     3165       +4     
==========================================
+ Hits         8056     8073      +17     
+ Misses       9307     9306       -1     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.