AshOaskit.RelationshipRoutes.RouteResponses (AshOasKit v0.2.1)

View Source

Response schema builders for relationship routes.

This module generates OpenAPI response schemas for JSON:API relationship endpoints, including both relationship linkage and related resource responses.

Response Types

Relationship Linkage Response

For relationship endpoints (/relationships/comments), the response contains resource identifier objects (type + id only):

%{
  "data" => [{"type": "comment", "id": "1"}, ...],
  "links" => {"self": "...", "related": "..."}
}

For related endpoints (/comments), the response contains full resource representations with pagination:

%{
  "data" => [full_resource_objects],
  "links" => {"self": "...", "first": "...", "next": "..."},
  "meta" => {"total": 42}
}

Cardinality

Schema structure varies by relationship cardinality:

  • to-one: Single resource identifier or null
  • to-many: Array of resource identifiers

Usage

schema = RouteResponses.build_relationship_linkage_schema(relationship, version: "3.1")
response = RouteResponses.build_related_response_schema(relationship, version: "3.1")

Summary

Functions

build_delete_relationship_responses()

Builds responses for relationship deletion routes.

build_modify_relationship_responses(route, opts, success_code)

Builds responses for relationship modification routes (POST/PATCH).

build_related_response_schema(relationship, opts)

Builds a related resources response schema.

build_related_responses(route, opts)

Builds responses for related resource routes.

build_relationship_linkage_schema(relationship, opts)

Builds a relationship linkage schema for response/request bodies.

build_relationship_response_schema(relationship, opts)

Builds a full relationship response schema with data and links.

build_relationship_responses(route, opts)

Builds responses for relationship linkage routes.

build_request_body(relationship, opts)

Builds the request body schema for relationship modification.

build_resource_identifier_schema(resource_type)

Builds the resource identifier schema for a resource type.

get_route_relationship(route)

Gets the relationship struct from a route.

relationship_cardinality(relationship)

Determines the cardinality of a relationship.

Functions

build_delete_relationship_responses()

@spec build_delete_relationship_responses() :: map()

Builds responses for relationship deletion routes.

Returns

A map of response code to response object.

build_modify_relationship_responses(route, opts, success_code)

@spec build_modify_relationship_responses(map(), keyword(), String.t()) :: map()

Builds responses for relationship modification routes (POST/PATCH).

Parameters

  • route - The AshJsonApi route struct
  • opts - Options keyword list
  • success_code - The success response code

Returns

A map of response code to response object.

build_relationship_linkage_schema(relationship, opts)

@spec build_relationship_linkage_schema(
  map() | struct(),
  keyword()
) :: map()

Builds a relationship linkage schema for response/request bodies.

For to-one relationships, returns a single resource identifier or null. For to-many relationships, returns an array of resource identifiers.

Parameters

  • relationship - The Ash relationship struct
  • opts - Options keyword list including :version

Returns

An OpenAPI schema object for relationship linkage.

build_relationship_response_schema(relationship, opts)

@spec build_relationship_response_schema(
  map() | struct(),
  keyword()
) :: map()

Builds a full relationship response schema with data and links.

Used for relationship routes that return linkage data.

Parameters

  • relationship - The Ash relationship struct
  • opts - Options keyword list

Returns

An OpenAPI schema object for a relationship response.

build_relationship_responses(route, opts)

@spec build_relationship_responses(
  map(),
  keyword()
) :: map()

Builds responses for relationship linkage routes.

Parameters

  • route - The AshJsonApi route struct
  • opts - Options keyword list

Returns

A map of response code to response object.

build_request_body(relationship, opts)

@spec build_request_body(
  map() | struct(),
  keyword()
) :: map()

Builds the request body schema for relationship modification.

Parameters

  • relationship - The Ash relationship struct
  • opts - Options keyword list

Returns

An OpenAPI request body object.

build_resource_identifier_schema(resource_type)

@spec build_resource_identifier_schema(String.t()) :: map()

Builds the resource identifier schema for a resource type.

A resource identifier object contains only the type and id fields, as defined by JSON:API for relationship linkage.

Parameters

  • resource_type - The JSON:API type name (string)

Returns

An OpenAPI schema object for a resource identifier.

Examples

iex> RouteResponses.build_resource_identifier_schema("comment")
%{
  type: :object,
  required: ["type", "id"],
  properties: %{
    "type" => %{type: :string, enum: ["comment"]},
    "id" => %{type: :string, description: "The unique identifier of the resource"}
  }
}

get_route_relationship(route)

@spec get_route_relationship(map()) :: map() | nil

Gets the relationship struct from a route.

Parameters

  • route - The AshJsonApi route struct

Returns

The relationship struct or nil.

relationship_cardinality(relationship)

@spec relationship_cardinality(map() | struct()) :: :one | :many

Determines the cardinality of a relationship.

Parameters

  • relationship - The Ash relationship struct

Returns

:one or :many.