[bcb37]

Ten @swagger annotations didn't describe the routes they document, so the generated spec advertises paths and payloads that don't exist. Comment-only — no routing or behaviour changes.

Found while regenerating the spec for the GitBook API reference: GitBook rejected the upload with processing errors, all of which traced back to these.

1. Literal path segments wrapped in braces

swagger-jsdoc reads {validation} as a path parameter named validation, which is then never declared:

Was	Now	Actual route
/experiments/{validation}	/experiments/validation	@Post('/validation')
/experiments/{import}	/experiments/import	@Post('/import')
/experiments/{export}	/experiments/export	@Get('/export')

2. Express-style parameter instead of Swagger templating

PUT /experiments/:id → /experiments/{id}. The DELETE on the same route was already annotated correctly, so the spec listed the two as separate paths. They now share one entry with both methods.

3. Path parameters declared with the wrong key

Five operations used id: or — copy-pasted out of the flag controller — flagId: where OpenAPI expects name:. The parameter was nameless and matched nothing in the path template:

• /experiments/export/includeLists/{id}
• /experiments/export/excludeLists/{id}
• /flags/export/{id}
• /flags/export/includeLists/{id}
• /flags/export/excludeLists/{id}

All five handlers bind :id, so name: id is correct for each.

4. GET /experiments/export had the import annotation copied onto it wholesale

It documented a required request body of experiment files, but the handler is @QueryParams() params: ExperimentIds and reads params.ids. Its 200 also claimed an array of {fileName, error} when it returns ExperimentDTO[].

Replaced with an in: query array of uuids (matching ExperimentIds: @IsArray @IsNotEmpty @IsUUID('all', {each: true}) ids: string[]) and a response referencing ExperimentResponse, the idiom GET /experiments/single/{id} already uses.

Verification

Regenerated the spec with the same swagger-jsdoc options as swaggerLoader.ts, before and after:

• Malformed paths: 9 → 0
• Operation count: 111 → 111 (unchanged — nothing gained or lost)
• Path count: 94 → 93 (PUT/DELETE now share /experiments/{id})

Confirmed the two POST body annotations on /experiments/validation and /experiments/import are correct as-is — in: body is right for a POST, and their schema matches ExperimentFile { fileName, fileContent }.

Not included

ExperimentClientController.v6.ts:1039 annotates DELETE /clearDB, but the handler sits under @JsonController('/v6/'), so the real route is /v6/clearDB. Left out deliberately — fixing it also means re-publishing the GitBook spec and updating the operation reference on the API reference page, so it's better handled alongside those.

🤖 Generated with Claude Code

[Copilot]

🟢 Approval recommended

There are no active review issues for the Swagger annotation updates.

No open issues 🎉

What changed in this PR

This comment-only PR aligns the backend’s Swagger annotations with existing experiment and feature flag endpoints, correcting generated API documentation without changing routing or runtime behavior.

Changes:

• Corrects literal route segments and Swagger path-parameter syntax.
• Replaces malformed parameter keys with name: id on five export operations.
• Documents experiment export with an ids query array and an ExperimentResponse array response.

File	Description
packages/​backend/​src/​api/​controllers/​FeatureFlagController.ts	Corrects path-parameter names in three export annotations.
packages/​backend/​src/​api/​controllers/​ExperimentController.ts	Corrects documented paths, export parameters, and the export response schema.

_{Review effort: Balanced}