Skip to content

feat(endpoint): include 422 validation-error response in endpoint namespace #283

Description

@yeongseon

Context

The endpoint metadata namespace (_endpoint.py, shipped via #275 under umbrella #270) currently emits a responses map that contains only the success status (success_status_code -> response object). It does not describe the standardized 422 validation-error response that @validate_http actually returns at runtime ({"detail": [{"loc", "msg", "type"}]}, see pipeline.py:222 and README "Status codes and controlled errors").

As a result, azure-functions-openapi cannot document the 422 contract from the shared namespace, so generated specs omit the error response even though runtime behavior is fixed and well-defined. This is the still-open P1 item "Validation error response schema 반영" from the v0.8 code review.

Note: this supersedes the stale #35, which was closed against the pre-endpoint-namespace design (enable_openapi_integration()), an API that no longer exists.

Target: keep ENDPOINT_METADATA_VERSION at 1 — this is an additive change to the responses map (consumers read defensively with .get()), no schema version bump.

Acceptance Checklist

  • build_endpoint_metadata adds a "422" entry to responses whenever any request model (body/query/path/headers) is present, using a self-contained JSON Schema for the {"detail": [...]} envelope (no model classes, no $ref leakage beyond the SPEC-pinned template).
  • The 422 schema matches the runtime envelope exactly (loc, msg, type item keys) — cross-checked against the golden tests in test_public_api.py / test_integration.py.
  • schemas/endpoint.schema.json + docs/METADATA_SPEC.md updated to document the 422 response shape; endpoint.schema.sha256 regenerated.
  • New unit test asserting the endpoint namespace responses contains both the success status and "422" with the correct schema.
  • Coverage stays >= 95% (make cov); make check-all green.
  • Translated READMEs updated if any English doc changes (per AGENTS.md).

Out of scope

References

Metadata

Metadata

Assignees

No one assigned

    Labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions