View Source Open API
Use with Phoenix
To set up the Open API endpoints for your application, first include the :open_api_spex
dependency:
{:open_api_spex, "~> 3.16"},
Then in the module where you call use AshJsonApi.Router
add the following option:
use AshJsonApi.Router, domains: [...], open_api: "/open_api"
Finally, you can use utilities provided by open_api_spex
to show UIs for your API. Be sure to put your forward
call last, if you are putting your API at a sub-path.
forward "/api/swaggerui",
OpenApiSpex.Plug.SwaggerUI,
path: "/api/open_api",
title: "Myapp's JSON-API - Swagger UI",
default_model_expand_depth: 4
forward "/api/redoc",
Redoc.Plug.RedocUI,
spec_url: "/api/open_api"
forward "/api", YourApp.YourApiRouter
Now you can go to /api/swaggerui
and /api/redoc
!
Use with Plug
To set up the open API endpoints for your application, first include the :open_api_spex
and :redoc_ui_plug
dependency:
{:open_api_spex, "~> 3.16"},
{:redoc_ui_plug, "~> 0.2.1"},
Then in the module where you call use AshJsonApi.Router
add the following option:
use AshJsonApi.Router, domains: [...], open_api: "/open_api"
Finally, you can use utilities provided by open_api_spex
to show UIs for your API. Be sure to put your forward
call last, if you are putting your API at a sub-path.
forward "/api/swaggerui",
to: OpenApiSpex.Plug.SwaggerUI,
init_opts: [
path: "/api/open_api",
title: "Myapp's JSON-API - Swagger UI",
default_model_expand_depth: 4
]
forward "/api/redoc",
to: Redoc.Plug.RedocUI,
init_opts: [
spec_url: "/api/open_api"
]
forward "/api", YourApp.YourApiRouter
Now you can go to /api/swaggerui
and /api/redoc
!
Customize values in the OpenAPI documentation
To override any value in the OpenApi documentation you can use the :modify_open_api
options key:
use AshJsonApi.Router,
domains: [...],
open_api: "/open_api",
modify_open_api: {__MODULE__, :modify_open_api, []}
def modify_open_api(spec, _, _) do
%{
spec
| info: %{spec.info | title: "MyApp Title JSON API", version: Application.spec(:my_app, :vsn) |> to_string()}
}
end
Known issues/limitations
Swagger UI
SwaggerUI does not properly render recursive types. This affects the examples and type documentation for the filter
parameter especially.
Redoc
Redoc does not show all available schemas in the sidebar. This means that some schemas that are referenced only but have no endpoints that refer to them are effectively un-discoverable without downloading the spec and hunting them down yourself.