AshOaskit.Config (AshOasKit v0.2.0)

View Source

Retrieves and normalizes configuration from AshJsonApi DSL.

This module provides a unified interface for accessing configuration options defined in Ash domains and resources through the AshJsonApi DSL.

Domain-Level Configuration

Domain-level configuration is retrieved via AshJsonApi.Domain.Info:

  • tag/1 - Custom OpenAPI tag for the domain
  • group_by/1 - How operations should be grouped (e.g., by resource)
  • prefix/1 - Route prefix for all resources in the domain

Resource-Level Configuration

Resource-level configuration is retrieved via AshJsonApi.Resource.Info:

  • type/1 - JSON:API type name (defaults to underscored resource name)
  • derive_filter?/1 - Whether to auto-generate filter schemas
  • derive_sort?/1 - Whether to auto-generate sort schemas
  • default_fields/1 - Default fields to include in responses
  • includes/1 - Available relationship includes

Usage

# Get the JSON:API type for a resource
type = Config.resource_type(MyApp.Post)
# => "post"

# Check if filtering should be derived
if Config.derive_filter?(MyApp.Post) do
  # Generate filter schema
end

# Get route prefix for a domain
prefix = Config.route_prefix(MyApp.Blog)
# => "/api/v1"

Error Handling

Functions in this module follow the "let it crash" philosophy. If called with an invalid module (not an Ash resource or domain), they will raise an error. This is intentional - configuration errors should fail loudly rather than silently returning defaults.

Summary

Functions

default_fields(resource)

Gets the default fields to include in responses for a resource.

derive_filter?(resource)

Checks whether filter schemas should be auto-derived for a resource.

derive_sort?(resource)

Checks whether sort schemas should be auto-derived for a resource.

domain_resources(domain)

Gets all resources in a domain.

domain_routes(domain)

Gets the JSON:API routes for a domain.

domain_tag(domain)

Gets the OpenAPI tag for a domain.

group_by(domain)

Gets the operation grouping strategy for a domain.

includes(resource)

Gets the available relationship includes for a resource.

primary_key(resource)

Gets the primary key field name(s) for a resource.

public_attributes(resource)

Gets the public attributes for a resource.

relationship(resource, name)

Gets a specific relationship for a resource by name.

relationships(resource)

Gets the relationships for a resource.

resource_action(resource, action_name)

Gets a specific action for a resource by name.

resource_actions(resource)

Gets the actions for a resource.

resource_type(resource)

Gets the JSON:API type name for a resource.

route_prefix(domain)

Gets the route prefix for a domain.

Functions

default_fields(resource)

@spec default_fields(module()) :: [atom()] | nil

Gets the default fields to include in responses for a resource.

If configured, responses will only include the specified fields unless the client requests additional fields via sparse fieldsets.

Parameters

  • resource - The Ash resource module

Returns

List of field names (as atoms) or nil for all fields.

Examples

iex> Config.default_fields(MyApp.Post)
[:id, :title, :body]

iex> Config.default_fields(MyApp.Comment)
nil

derive_filter?(resource)

@spec derive_filter?(module()) :: boolean()

Checks whether filter schemas should be auto-derived for a resource.

When enabled, the OpenAPI generator will create detailed filter parameter schemas based on the resource's attributes.

Parameters

  • resource - The Ash resource module

Returns

Boolean indicating if filter derivation is enabled.

Examples

iex> Config.derive_filter?(MyApp.Post)
true

derive_sort?(resource)

@spec derive_sort?(module()) :: boolean()

Checks whether sort schemas should be auto-derived for a resource.

When enabled, the OpenAPI generator will create sort parameter schemas listing all sortable fields.

Parameters

  • resource - The Ash resource module

Returns

Boolean indicating if sort derivation is enabled.

Examples

iex> Config.derive_sort?(MyApp.Post)
true

domain_resources(domain)

@spec domain_resources(module()) :: [module()]

Gets all resources in a domain.

Parameters

  • domain - The Ash domain module

Returns

List of resource modules.

Examples

iex> Config.domain_resources(MyApp.Blog)
[MyApp.Post, MyApp.Comment, MyApp.Author]

domain_routes(domain)

@spec domain_routes(module()) :: [map()]

Gets the JSON:API routes for a domain.

Parameters

  • domain - The Ash domain module

Returns

List of route structs.

Examples

Config.domain_routes(MyApp.Blog)
# => [%{type: :index, ...}, %{type: :get, ...}, ...]

domain_tag(domain)

@spec domain_tag(module()) :: String.t() | nil

Gets the OpenAPI tag for a domain.

Tags are used to group operations in OpenAPI documentation tools like Swagger UI.

Parameters

  • domain - The Ash domain module

Returns

The tag name as a string, or nil if not configured.

Examples

iex> Config.domain_tag(MyApp.Blog)
"Blog"

group_by(domain)

@spec group_by(module()) :: atom() | nil

Gets the operation grouping strategy for a domain.

Determines how operations are grouped in the OpenAPI spec.

Parameters

  • domain - The Ash domain module

Returns

The grouping strategy atom (e.g., :resource, :domain), or nil.

Examples

iex> Config.group_by(MyApp.Blog)
:resource

includes(resource)

@spec includes(module()) :: [atom() | String.t()] | nil

Gets the available relationship includes for a resource.

Defines which relationships can be included via the include query parameter. Returns nil if not configured.

Parameters

  • resource - The Ash resource module

Returns

List of includable relationship paths, or nil if not configured.

Examples

iex> Config.includes(MyApp.Post)
[:author, :comments, "comments.author"]

primary_key(resource)

@spec primary_key(module()) :: [atom()]

Gets the primary key field name(s) for a resource.

Parameters

  • resource - The Ash resource module

Returns

List of primary key field names (as atoms).

Examples

iex> Config.primary_key(MyApp.Post)
[:id]

public_attributes(resource)

@spec public_attributes(module()) :: [map()]

Gets the public attributes for a resource.

Returns only attributes marked public? true, which are the ones that belong in OpenAPI schemas.

Parameters

  • resource - The Ash resource module

Returns

List of attribute structs.

relationship(resource, name)

@spec relationship(module(), atom()) :: map() | nil

Gets a specific relationship for a resource by name.

Parameters

  • resource - The Ash resource module
  • name - The relationship name (atom)

Returns

The relationship struct or nil if not found.

relationships(resource)

@spec relationships(module()) :: [map()]

Gets the relationships for a resource.

Parameters

  • resource - The Ash resource module

Returns

List of relationship structs.

resource_action(resource, action_name)

@spec resource_action(module(), atom()) :: map() | nil

Gets a specific action for a resource by name.

Parameters

  • resource - The Ash resource module
  • action_name - The action name (atom)

Returns

The action struct or nil if not found.

resource_actions(resource)

@spec resource_actions(module()) :: [map()]

Gets the actions for a resource.

Parameters

  • resource - The Ash resource module

Returns

List of action structs.

resource_type(resource)

@spec resource_type(module()) :: String.t()

Gets the JSON:API type name for a resource.

The type is used in JSON:API responses as the type field and in route generation. If not explicitly configured, defaults to the underscored resource module name.

Parameters

  • resource - The Ash resource module

Returns

The JSON:API type as a string.

Examples

iex> Config.resource_type(MyApp.BlogPost)
"blog_post"

iex> Config.resource_type(MyApp.User)
"user"

route_prefix(domain)

@spec route_prefix(module()) :: String.t()

Gets the route prefix for a domain.

The prefix is prepended to all resource routes in the domain.

Parameters

  • domain - The Ash domain module

Returns

The route prefix as a string (empty string if not configured).

Examples

iex> Config.route_prefix(MyApp.Blog)
"/api/v1"

iex> Config.route_prefix(MyApp.Admin)
"/admin"