OpenApiSpex.Operation (open_api_spex v3.21.3)

Defines the OpenApiSpex.Operation.t type.

Summary

Types

t()

Operation Object

Functions

cast(operation, conn, content_type, schemas)

Cast params to the types defined by the schemas of the operation parameters and requestBody

from_plug(plug, opts)

Constructs an Operation struct from plug module and opts

from_route(route)

Constructs an Operation struct from the plug and opts specified in the given route

parameter(name, location, type, description, opts \\ [])

Shorthand for constructing an OpenApiSpex.Parameter given name, location, type, description and optional examples

request_body(description, media_type, schema_ref, opts \\ [])

Shorthand for constructing a RequestBody with description, media_type, schema and optional examples

response(description, media_type, schema_ref, opts \\ [])

Shorthand for constructing a Response with description, media_type, schema and optional headers or examples

validate(operation, conn, content_type, schemas)

Validate params against the schemas of the operation parameters and requestBody

Types

t()

@type t() :: %OpenApiSpex.Operation{
  callbacks: %{
    required(String.t()) => OpenApiSpex.Callback.t() | OpenApiSpex.Reference.t()
  },
  deprecated: boolean(),
  description: String.t() | nil,
  extensions: %{required(String.t()) => any()} | nil,
  externalDocs: OpenApiSpex.ExternalDocumentation.t() | nil,
  operationId: String.t() | nil,
  parameters: [OpenApiSpex.Parameter.t() | OpenApiSpex.Reference.t()],
  requestBody: OpenApiSpex.RequestBody.t() | OpenApiSpex.Reference.t() | nil,
  responses: OpenApiSpex.Responses.t(),
  security: [OpenApiSpex.SecurityRequirement.t()] | nil,
  servers: [OpenApiSpex.Server.t()] | nil,
  summary: String.t() | nil,
  tags: [String.t()]
}

Operation Object

Describes a single API operation on a path.

Functions

cast(operation, conn, content_type, schemas)

@spec cast(
  t(),
  Plug.Conn.t(),
  content_type :: String.t() | nil,
  schemas :: %{required(String.t()) => OpenApiSpex.Schema.t()}
) :: {:ok, Plug.Conn.t()} | {:error, String.t()}

Cast params to the types defined by the schemas of the operation parameters and requestBody

from_plug(plug, opts)

@spec from_plug(module(), opts :: any()) :: t() | nil

Constructs an Operation struct from plug module and opts

from_route(route)

@spec from_route(OpenApiSpex.PathItem.route()) :: t() | nil

Constructs an Operation struct from the plug and opts specified in the given route

parameter(name, location, type, description, opts \\ [])

@spec parameter(
  name :: atom(),
  location :: OpenApiSpex.Parameter.location(),
  type ::
    OpenApiSpex.Reference.t()
    | OpenApiSpex.Schema.t()
    | OpenApiSpex.Parameter.type()
    | atom(),
  description :: String.t(),
  opts :: keyword()
) :: OpenApiSpex.Parameter.t()

Shorthand for constructing an OpenApiSpex.Parameter given name, location, type, description and optional examples

Examples

iex> Operation.parameter(
...>   :status,
...>   :query,
...>   %OpenApiSpex.Schema{type: :string, enum: ["pending", "in_progress", "completed"]},
...>   "The status of an entity"
...> )
%OpenApiSpex.Parameter{
  name: :status,
  in: :query,
  description: "The status of an entity",
  required: false,
  schema: %OpenApiSpex.Schema{enum: ["pending", "in_progress", "completed"], type: :string}
}

request_body(description, media_type, schema_ref, opts \\ [])

@spec request_body(
  description :: String.t(),
  media_type ::
    String.t()
    | %{required(String.t()) => Keyword.t() | OpenApiSpex.MediaType.t()},
  schema_ref :: OpenApiSpex.Schema.t() | OpenApiSpex.Reference.t() | module(),
  opts :: keyword()
) :: OpenApiSpex.RequestBody.t()

Shorthand for constructing a RequestBody with description, media_type, schema and optional examples

response(description, media_type, schema_ref, opts \\ [])

@spec response(
  description :: String.t(),
  media_type ::
    String.t()
    | %{required(String.t()) => Keyword.t() | OpenApiSpex.MediaType.t()}
    | nil,
  schema_ref ::
    OpenApiSpex.Schema.t() | OpenApiSpex.Reference.t() | module() | nil,
  opts :: keyword()
) :: OpenApiSpex.Response.t()

Shorthand for constructing a Response with description, media_type, schema and optional headers or examples

validate(operation, conn, content_type, schemas)

@spec validate(t(), Plug.Conn.t(), String.t() | nil, %{
  required(String.t()) => OpenApiSpex.Schema.t()
}) ::
  :ok | {:error, String.t()}

Validate params against the schemas of the operation parameters and requestBody