AshOaskit.RelationshipRoutes.RouteOperations (AshOasKit v0.2.0)

Operation builders for relationship routes.

This module generates OpenAPI operation objects for JSON:API relationship endpoints, including operation metadata, parameters, and routing to appropriate response builders.

Operations

Each relationship route type generates a different operation:

Route Type	Method	Operation ID Pattern
`:related`	GET	`{resource}_{rel}_related`
`:relationship`	GET	`{resource}_{rel}_relationship`
`:post_to_relationship`	POST	`{resource}_{rel}_add`
`:patch_relationship`	PATCH	`{resource}_{rel}_replace`
`:delete_from_relationship`	DELETE	`{resource}_{rel}_remove`

Parameters

Path parameters are extracted from the route pattern (e.g., :id). For :related routes the JSON:API query parameter set is added against the destination resource (see build_parameters/2).

Usage

operation = RouteOperations.build_operation(route, version: "3.1")

Summary

Functions

build_description(route)

Builds the description text for a relationship route.

build_operation(route, opts \\ [])

Builds an OpenAPI operation object for a relationship route.

build_operation_id(route)

Builds the operation ID for a relationship route.

build_parameters(route, opts \\ [])

Builds the parameters for a relationship route.

build_summary(route)

Builds the summary text for a relationship route.

build_tags(route)

Builds the tags for a relationship route.

Functions

build_description(route)

@spec build_description(map()) :: String.t() | nil

Builds the description text for a relationship route.

A description set on the route takes precedence over the canned per-route-type text.

Parameters

route - An AshJsonApi route struct

Returns

A description string or nil.

build_operation(route, opts \\ [])

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

Builds an OpenAPI operation object for a relationship route.

Generates the complete operation including operationId, summary, description, tags, parameters, responses, and optional request body.

Parameters

route - An AshJsonApi route struct
opts - Options keyword list including :version

Returns

A map representing the OpenAPI operation object.

build_operation_id(route)

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

Builds the operation ID for a relationship route.

Parameters

route - An AshJsonApi route struct

Returns

A unique operation identifier string.

build_parameters(route, opts \\ [])

@spec build_parameters(
  map(),
  keyword()
) :: [map()]

Builds the parameters for a relationship route.

Extracts path parameters. For :related GET routes, which serve the DESTINATION resource, the JSON:API query parameter set is added:

to-many relationships: filter and sort built against the destination resource (gated on the route's derive_filter? / derive_sort? flags and the destination's own settings), plus page and include
to-one relationships: include only

Relationship linkage routes (:relationship and modifications) take only path parameters.

Parameters

route - An AshJsonApi route struct
opts - Options keyword list including :version

Returns

A list of parameter objects.

build_summary(route)

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

Builds the summary text for a relationship route.

Parameters

route - An AshJsonApi route struct

Returns

A human-readable summary string.

build_tags(route)

@spec build_tags(map()) :: [String.t()]

Builds the tags for a relationship route.

Parameters

route - An AshJsonApi route struct

Returns

A list of tag strings.