Reuses an existing OpenApiSpex spec module.
Phoenix applications that already describe their API with OpenApiSpex have a
module exporting spec/0. There is no reason to describe the same API twice,
so this adapter calls it and feeds the result into the build:
config :doc_shell,
open_api_adapter: DocShell.Generate.OpenApi.Adapters.OpenApiSpex,
open_api_options: [module: MyAppWeb.ApiSpec]The :module option is required — unlike Ash domains there is no useful
default, and guessing at a module name would fail in a confusing way.
Structs and maps
spec/0 normally returns an %OpenApiSpex.OpenApi{} struct, which is not
JSON-shaped: it uses atom keys and Elixir-cased field names. The adapter
round-trips it through Jason, which applies OpenApiSpex's own encoder and
yields the same document the library would serve over HTTP. A module that
already returns a plain map is passed through untouched, so hand-rolled spec
modules work too.
OpenApiSpex is not a dependency of DocShell. The module is resolved at runtime, and a host that does not configure this adapter never loads it.
Errors
{:error, :open_api_spex_source_unavailable}— no:moduleoption, or the module is missing or does not exportspec/0{:error, :invalid_open_api_spex_spec}—spec/0returned something that is not a map or struct{:error, :open_api_spex_spec_not_json_encodable}— the struct has no usable JSON encoding