@spec build_param_specs(ExOpenAI.Codegen.DocsParser.Operation.t(), [atom()], %{
  required(String.t()) => ExOpenAI.Codegen.DocsParser.Schema.t()
}) :: [Macro.t()]

Builds parameter type specifications for a function.

Takes an operation and its argument names, and generates proper typespecs for each parameter. This includes:

• Path parameters (from operation.parameters where in="path")
• Required body parameters (from request body schema)
• Optional parameters in the opts keyword list

Parameters

• operation - The Operation struct containing parameter definitions
• arg_names - List of argument names (atoms) for the function
• schemas - Map of component schemas for type resolution

Returns

A list of AST nodes representing the typespec for each parameter.

Example

iex> operation = %Operation{
...>   parameters: [%{name: "id", in: "path", schema: %{"type" => "string"}}],
...>   request_body: %{content: %{"application/json" => %{...}}}
...> }
iex> build_param_specs(operation, [:id, :name, :opts], schemas)
[{:"::", [], [{:id, [], nil}, {:remote_type, [], [...]}]}, ...]

@spec build_positional_param_spec(
  ExOpenAI.Codegen.DocsParser.Operation.t(),
  atom(),
  ExOpenAI.Codegen.DocsParser.Schema.t() | nil,
  %{optional(String.t()) => ExOpenAI.Codegen.DocsParser.Schema.t()}
) :: Macro.t()

Builds the typespec for a single positional parameter.

Determines whether the parameter is a path parameter or body parameter and generates the appropriate typespec.

Parameters

• operation - The Operation struct
• arg_name - The parameter name as an atom
• body_schema - The resolved request body schema (may be nil)

Returns

An AST node representing the parameter typespec.

@spec build_return_spec(ExOpenAI.Codegen.DocsParser.Operation.t(), atom(), %{
  required(String.t()) => ExOpenAI.Codegen.DocsParser.Schema.t()
}) :: Macro.t()

Builds the return type specification for a function.

Determines the appropriate return type based on:

• Response schemas defined in the operation
• Whether the function is an explicit streaming helper (*_stream)
• Whether the endpoint supports stream: true on the normal function

Parameters

• operation - The Operation struct containing response definitions
• function_name - The function name (used to detect explicit streaming helpers)
• schemas - Map of component schemas for type resolution

Returns

An AST node representing the return type, typically:

• {:ok, ComponentType.t()} | {:error, any()} for normal endpoints

• {:ok, reference()} | {:error, any()} for explicit streaming helpers

• {:ok, ComponentType.t() | reference()} | {:error, any()} for endpoints that switch behavior with stream: true

@spec determine_param_type(
  ExOpenAI.Codegen.DocsParser.Operation.t(),
  atom(),
  ExOpenAI.Codegen.DocsParser.Schema.t() | nil,
  %{optional(String.t()) => ExOpenAI.Codegen.DocsParser.Schema.t()}
) :: Macro.t()

Determines the type specification for a parameter.

Checks if the parameter is a path parameter first, then checks if it's a body parameter. Returns the appropriate typespec AST.

Parameters

• operation - The Operation struct containing parameter definitions
• arg_name - The parameter name as an atom
• body_schema - The resolved request body schema (may be nil)

Returns

An AST node representing the type (e.g., String.t(), integer(), etc.)

@spec generate_doc(ExOpenAI.Codegen.DocsParser.Operation.t(), %{
  required(String.t()) => ExOpenAI.Codegen.DocsParser.Schema.t()
}) :: Macro.t()

Generates @doc attribute for an operation.

Uses the operation's summary and description, plus parameter documentation.

@spec generate_spec(ExOpenAI.Codegen.DocsParser.Operation.t(), atom(), [atom()], %{
  required(String.t()) => ExOpenAI.Codegen.DocsParser.Schema.t()
}) :: Macro.t()

Generates @spec attribute for an operation function.

Builds proper typespecs for all parameters and return types.