# `DocShell.Generate.OpenApi.Adapters.OpenApiSpex`
[🔗](https://github.com/futhr/doc_shell/blob/v2.0.0/lib/doc_shell/generate/open_api/adapters/open_api_spex.ex#L1)

Reuses an existing [OpenApiSpex](https://hexdocs.pm/open_api_spex) 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 `:module` option, or
    the module is missing or does not export `spec/0`
  * `{:error, :invalid_open_api_spex_spec}` — `spec/0` returned something
    that is not a map or struct
  * `{:error, :open_api_spex_spec_not_json_encodable}` — the struct has no
    usable JSON encoding

---

*Consult [api-reference.md](api-reference.md) for complete listing*