[Prachi194agrawal]

Fixes #2331

POST /api/v3/packages/ returns paginated PURL strings when details=false and package objects when details=true. The schema currently describes only package objects, preventing generated clients from correctly handling both response formats.

This change describes the paginated results using oneOf for PURL strings and detailed package objects. It also documents nullable fields and conditional advisory lists or URLs in detailed responses.

Adds regression tests that validate actual API responses against the generated OpenAPI schema, covering:

• Both details modes and empty results.
• Queries with an empty PURL list.
• Nullable version and risk fields.
• Advisory URLs returned when max_advisories is exceeded.
• Rejection of malformed response structures.
• HTTPS pagination links when the forwarded protocol is supplied.

The tests also verify that the schema retains the correct HTTP 200 response.

Validation

venv/bin/python -m pytest vulnerabilities/tests/test_api_v3.py --reuse-db -q

Result: 27 passed, 42 warnings.