AshOaskit.QueryParameters (AshOasKit v0.2.0)

View Source

Generates detailed JSON:API query parameter schemas for OpenAPI specs.

This module provides comprehensive query parameter schemas for JSON:API compliant APIs, including pagination, sparse fieldsets, includes, filtering, and sorting.

JSON:API Query Parameters

The JSON:API specification defines several query parameters:

Page Parameter

Pagination can use either offset-based or keyset/cursor-based strategies:

# Offset pagination
GET /posts?page[offset]=0&page[limit]=10

# Keyset pagination
GET /posts?page[after]=cursor&page[limit]=10

# With count
GET /posts?page[count]=true

Fields Parameter (Sparse Fieldsets)

Request specific fields per resource type:

GET /posts?fields[post]=title,body&fields[author]=name

Include Parameter

Include related resources:

GET /posts?include=author,comments.author

Filter Parameter

Filter resources using various operators:

GET /posts?filter[status]=published&filter[title][contains]=hello

Sort Parameter

Sort resources by fields:

GET /posts?sort=-created_at,title

Usage

# Build page parameter for a resource
page_param = QueryParameters.build_page_parameter(opts)

# Build fields parameter with resource types
fields_param = QueryParameters.build_fields_parameter(["post", "author"])

# Build include parameter with relationship paths
include_param = QueryParameters.build_include_parameter([:author, :comments])

# Get all standard JSON:API parameters
params = QueryParameters.all_parameters(resource, opts)

Summary

Functions

all_parameters(resource, opts \\ [])

Builds all standard JSON:API query parameters for a resource.

basic_parameters(resource, opts \\ [])

Builds a read-only parameters list (no filter/sort).

build_fields_parameter(resource_types, _ \\ [])

Builds the fields query parameter schema for sparse fieldsets.

build_include_parameter(available_includes, _ \\ [])

Builds the include query parameter schema.

build_page_parameter(opts \\ [])

Builds the page query parameter schema.

index_parameters(resource, opts \\ [])

Builds parameters for index/list operations.

show_parameters(resource, opts \\ [])

Builds parameters for get/show operations.

Functions

all_parameters(resource, opts \\ [])

@spec all_parameters(
  module(),
  keyword()
) :: [map()]

Builds all standard JSON:API query parameters for a resource.

Combines filter, sort, page, include, and fields parameters.

Parameters

  • resource - The Ash resource module
  • opts - Options keyword list
    • :version - OpenAPI version ("3.0" or "3.1")
    • :pagination_strategy - Pagination type
    • :include_paths - Available include paths

Returns

List of OpenAPI parameter objects.

Examples

QueryParameters.all_parameters(MyApp.Post, version: "3.1")
#=> [
#=>   %{name: "filter", ...},
#=>   %{name: "sort", ...},
#=>   %{name: "page", ...},
#=>   %{name: "include", ...},
#=>   %{name: "fields", ...}
#=> ]

basic_parameters(resource, opts \\ [])

@spec basic_parameters(
  module(),
  keyword()
) :: [map()]

Builds a read-only parameters list (no filter/sort).

Useful for simple GET operations that don't support filtering.

Parameters

  • resource - The Ash resource module
  • opts - Options keyword list

Returns

List of OpenAPI parameter objects (page, include, fields only).

build_fields_parameter(resource_types, _ \\ [])

@spec build_fields_parameter(
  [String.t()],
  keyword()
) :: map()

Builds the fields query parameter schema for sparse fieldsets.

Parameters

  • resource_types - List of JSON:API type names
  • opts - Options keyword list

Returns

An OpenAPI parameter object for sparse fieldsets.

Examples

iex> QueryParameters.build_fields_parameter(["post", "author"])
%{
  name: "fields",
  in: :query,
  style: :deepObject,
  schema: %{
    type: :object,
    properties: %{
      "post" => %{type: :string},
      "author" => %{type: :string}
    }
  }
}

build_include_parameter(available_includes, _ \\ [])

@spec build_include_parameter(
  [atom() | String.t()],
  keyword()
) :: map()

Builds the include query parameter schema.

Parameters

  • available_includes - List of includable relationship paths
  • opts - Options keyword list

Returns

An OpenAPI parameter object for relationship includes.

Examples

iex> QueryParameters.build_include_parameter([:author, :comments])
%{
  name: "include",
  in: :query,
  schema: %{
    type: :string,
    description: "..."
  }
}

build_page_parameter(opts \\ [])

@spec build_page_parameter(keyword()) :: map()

Builds the page query parameter schema.

Supports both offset and keyset pagination strategies.

Parameters

  • opts - Options keyword list
    • :pagination_strategy - :offset, :keyset, or :both (default)

Returns

An OpenAPI parameter object for pagination.

Examples

iex> QueryParameters.build_page_parameter([])
%{
  name: "page",
  in: :query,
  style: :deepObject,
  schema: %{
    type: :object,
    properties: %{
      "offset" => %{...},
      "limit" => %{...},
      ...
    }
  }
}

index_parameters(resource, opts \\ [])

@spec index_parameters(
  module(),
  keyword()
) :: [map()]

Builds parameters for index/list operations.

Includes all standard parameters plus optional count parameter.

Parameters

  • resource - The Ash resource module
  • opts - Options keyword list

Returns

List of OpenAPI parameter objects.

show_parameters(resource, opts \\ [])

@spec show_parameters(
  module(),
  keyword()
) :: [map()]

Builds parameters for get/show operations.

Typically only needs include and fields parameters.

Parameters

  • resource - The Ash resource module
  • opts - Options keyword list

Returns

List of OpenAPI parameter objects.