More content output representations

[eviltester]

In Thingifier add support for more output content representations

• text/csv - best for collections; ok for single instances.
• text/plain - simple line-based output, human readable but not structured
• text/html - useful to show that APIs can return browser-renderable representations too.
• application/x-ndjson or application/jsonl - one JSON object per line; good for streamed/exported collections. (but we would not add streaming)
• application/json-seq - standardized JSON text sequence
• text/tab-separated-values - TSV, could possibly build on CSV

these would be generated based on the GET QUERY accept headers

[eviltester]

Implementation Plan: Additional Response Representations

Implement Accept-header based response selection while preserving the existing JSON/XML defaults and the current first-supported Accept-header priority behaviour. No q-value parsing in this change.

1. Centralise supported response media types

• Replace the JSON/XML boolean selection in HttpApiResponse with a selected response representation/media-type model.
• Use an enum to own all supported Accept/header media types, including:
  • application/json
  • application/xml
  • text/csv
  • text/plain
  • text/html
  • application/x-ndjson
  • application/jsonl
  • application/json-seq
  • text/tab-separated-values
  • existing wildcard handling for application/* and */*
• Expose the concrete response media types from the enum as RESPONSE_MEDIA_TYPES or equivalent, so docs and serializers do not maintain separate hard-coded lists.

2. Extend Accept parsing and validation

• Update Accept-header parsing to match exact supported media types first, including the new formats.
• Preserve first-supported priority across comma-separated Accept values.
• Keep existing wildcard behaviour for application/* and */*.
• Continue returning the configured 406 response for unsupported media types when Accept enforcement is enabled.
• Keep JSON/XML allow flags scoped to JSON/XML only; they should not disable the new non-JSON/XML representations.

3. Add serializers from the existing ApiResponse model

• CSV and TSV:
  • header row plus one row per returned entity
  • response-visible scalar fields only
  • preserve entity field order
  • skip object fields and relationships
  • quote CSV values correctly and escape TSV line/tab characters
• Plain text:
  • one entity per line as field=value pairs
  • error responses as one message per line
• HTML:
  • simple escaped table for entity responses
  • escaped list for error responses
• NDJSON and JSONL:
  • one unwrapped JSON object per line
  • same body shape for both, with requested Content-Type
• JSON sequence:
  • prefix each JSON text with ASCII RS (\u001E)
  • terminate each JSON text with \n

4. Preserve existing response behaviour

• Preserve body overrides, no-body responses, status codes, custom headers, entity views, and current JSON/XML output.
• Default paths should remain compatible with current clients.
• Avoid streaming in this issue; generate line-oriented formats from the completed response.

5. Update documentation generation

• Update OpenAPI generation so documented response bodies advertise every supported response media type.
• Keep JSON/XML schemas as they are today.
• Document non-JSON/XML OpenAPI media entries as string payloads.
• Update generated HTML API documentation so the Accept examples mention the new values.

6. Test coverage

Add focused tests for:

• Accept parser and validator handling of each new media type, wildcard fallback, unsupported media, aliases, disabled JSON/XML settings, and first-supported priority.
• Serializers for single entity, collection, empty collection, errors, entity-view filtering, object-field skipping, CSV quoting, TSV escaping, HTML escaping, and JSON-seq framing.
• HTTP GET and QUERY responses selecting each new Content-Type and representative body output.
• OpenAPI and HTML documentation advertising the new response media types.

Run the full module verification with:

mvn -pl thingifier -am -DfailIfNoTests=false test

[eviltester]

Work Done: Additional Response Representations

Implemented locally on branch codex/91-more-content-output-representations.

Completed changes

• Replaced the old JSON/XML boolean response choice in HttpApiResponse with enum-based response media selection.
• Centralised all supported response media types in AcceptHeaderParser.ACCEPT_TYPE, including helper methods for concrete response media types and documentation/schema behaviour. This keeps JSON, XML, CSV, plain text, HTML, NDJSON, JSONL, JSON sequence, and TSV in one place rather than spreading hard-coded media strings through Swagger/doc generation and serializers.
• Extended Accept-header parsing and validation for:
  • text/csv
  • text/plain
  • text/html
  • application/x-ndjson
  • application/jsonl
  • application/json-seq
  • text/tab-separated-values
  • existing application/json, application/xml, application/*, and */* behaviour
• Preserved first-supported Accept priority and did not add q-value parsing.
• Kept JSON/XML allow flags scoped to JSON/XML only, so disabled JSON/XML can fall through to other supported representations.
• Added serializers from the existing ApiResponse model:
  • CSV/TSV via ApiResponseAsDelimitedText
  • plain text via ApiResponseAsPlainText
  • HTML via ApiResponseAsHtml
  • NDJSON/JSONL/JSON-seq via ApiResponseAsJsonLines
  • shared row extraction via ApiResponseBodyRows
• Preserved existing JSON/XML output, body overrides, no-body responses, status codes, custom headers, and entity-view filtering.
• Updated Swagger/OpenAPI generation so all response media types are advertised, with JSON/XML using existing schemas and the new text-like formats documented as string payloads.
• Updated generated HTML API documentation to list the expanded Accept values.

Test coverage added/updated

• Accept parser tests for exact media types, wildcards, unsupported values, alias handling, and first-supported priority.
• Accept validator tests for new media types and JSON/XML disabled fallback behaviour.
• Serializer tests for single entities, collections, empty collections, errors, entity views, object-field skipping, CSV quoting, TSV escaping, HTML escaping, and JSON-seq framing.
• HTTP GET and QUERY tests for representative output and selected Content-Type across the new formats.
• Documentation tests for OpenAPI and generated HTML Accept documentation.

Verification

• mvn -pl thingifier -am -DfailIfNoTests=false test passed.
• Full repo clean test run passed after freeing local port 4567 from an unrelated running Challenger app:

mvn -q -DfailIfNoTests=false clean test

Result: 971 tests, 0 failures, 0 errors, 0 skipped.