Updates api docs

[seb-kw]

No description provided.

[Copilot]

Pull request overview

Updates the generated OpenAPI specs and related controller Swagger annotations to reflect new/updated API fields and endpoints (notably around org config files, asset version DTOs, and artifact export formats).

Changes:

• Added new schema fields (e.g., directDependencyFixedVersion, “fixable” counters) to Swagger components.
• Extended/adjusted API paths for org config files (PUT) and artifact exports (OpenVEX JSON, SBOM/VEX XML, SBOM/vulnerability-report PDFs).
• Updated asset version endpoints to reference dtos.AssetVersionDTO in controller annotations and Swagger output.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 15 comments.

Show a summary per file

File	Description
docs/swagger.yaml	Regenerated OpenAPI YAML with new fields/endpoints and updated schemas.
docs/swagger.json	Regenerated OpenAPI JSON mirroring the YAML changes.
controllers/org_controller.go	Updated Swagger annotation to correctly mark config file content as a request body param.
controllers/asset_version_controller.go	Updated Swagger success types to dtos.AssetVersionDTO for asset version endpoints.
controllers/artifact_controller.go	Added Swagger-documented artifact export endpoints (XML/PDF/OpenVEX) and adjusted routes to match trailing-slash router paths.

Comments suppressed due to low confidence (1)

controllers/artifact_controller.go:510

• VEXXML writes an XML CycloneDX document but does not set a Content-Type response header. Consider setting an explicit XML content type before encoding to ensure clients interpret the response correctly.

	if err != nil {
		return err
	}

	encoder := cdx.NewBOMEncoder(ctx.Response().Writer, cdx.BOMFileFormatXML).SetPretty(true).SetEscapeHTML(false)

	return encoder.Encode(sbom.ToCycloneDX(ctxToBOMMetadata(ctx)))
}

---

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

[Copilot]

The Swagger annotation @Success 200 {array} []dtos.AssetVersionDTO is generating an array-of-arrays in the OpenAPI spec (see docs/swagger.yaml paths /.../refs response schema). For swaggo, the element type should be the DTO itself; otherwise clients will think the endpoint returns [][]AssetVersionDTO instead of []AssetVersionDTO.

[Copilot]

The response schema for GET /organizations/.../refs is currently documented as an array whose items are arrays (nested items + type: array). This should be a single-level array of dtos.AssetVersionDTO; otherwise generated clients will expect [][]AssetVersionDTO. This likely comes from the controller annotation using []dtos.AssetVersionDTO as the array element type.

[Copilot]

The OpenAPI response schema for GET /organizations/.../refs is an array-of-arrays (items contains another items + type: array). This should be a single-level array of dtos.AssetVersionDTO, otherwise generated clients will model the response as [][]AssetVersionDTO.

[Copilot]

SBOMXML returns an XML-encoded CycloneDX document but does not set a Content-Type response header (unlike SBOMJSON which sets application/json). Setting an explicit XML content type (e.g., application/xml or a CycloneDX-specific XML media type) avoids incorrect client/content negotiation behavior.

[Copilot]

These endpoints generate a PDF response (Content-Type: application/pdf is set in the handler), but the Swagger annotations still declare a generic {object} object success type and don't declare the produced media type. This causes the generated OpenAPI (docs/swagger.*) to advertise application/json for PDF downloads. Update the annotations to declare the correct @Produce (application/pdf) and a binary/string response schema so clients can handle the response correctly.

[Copilot]

The Swagger annotations for this endpoint describe a generic {object} object success type, but the handler returns CycloneDX XML. Add an explicit produced media type for XML and a more accurate response schema so the generated OpenAPI doesn’t incorrectly advertise application/json.

[Copilot]

The Swagger annotations for this endpoint describe a generic {object} object response, but the handler returns CycloneDX XML. Add an explicit produced media type for XML and an accurate response schema so the generated OpenAPI matches the actual response format.

[Copilot]

This SBOM XML endpoint is documented as returning application/json with an object schema. Since it returns XML, the OpenAPI response should use an XML media type (e.g., application/xml) with an appropriate string/binary schema so client generators handle it correctly.

[Copilot]

This VEX XML endpoint is documented as returning application/json with an object schema, but it returns XML. Update the OpenAPI response content type to an XML media type and use an appropriate string/binary schema so generated clients don’t treat it as JSON.

[Copilot]

The OpenAPI spec for this SBOM XML endpoint advertises application/json with type: object, but the handler returns an XML document. Update the response content type to an XML media type and use a string/binary schema so generated clients don’t treat it as JSON.