Packages
ash_json_api
1.3.3
1.7.1
1.7.0
1.6.6
1.6.5
1.6.4
1.6.3
1.6.2
1.6.1
1.6.0-rc.2
1.6.0-rc.1
1.6.0-rc.0
1.5.1
1.5.0
1.4.45
1.4.44
1.4.43
1.4.42
1.4.41
1.4.40
1.4.39
1.4.38
1.4.37
1.4.36
1.4.35
1.4.34
1.4.33
1.4.32
1.4.31
1.4.30
1.4.29
1.4.28
1.4.27
1.4.26
1.4.25
1.4.24
1.4.23
1.4.22
1.4.21
1.4.20
1.4.19
1.4.18
1.4.17
1.4.16
1.4.15
1.4.13
1.4.12
1.4.11
1.4.10
1.4.9
1.4.8
1.4.7
1.4.6
1.4.5
1.4.4
1.4.3
1.4.2
1.4.1
1.4.0
1.3.8
1.3.7
1.3.6
1.3.5
1.3.4
retired
1.3.3
1.3.2
1.3.1
1.3.0
1.2.2
1.2.1
1.2.0
1.1.2
1.1.1
1.1.0
1.0.0
1.0.0-rc.6
1.0.0-rc.5
1.0.0-rc.4
1.0.0-rc.3
1.0.0-rc.2
1.0.0-rc.1
1.0.0-rc.0
0.34.2
0.34.1
0.34.0
0.33.1
0.33.0
0.32.1
0.32.0
0.31.3
0.31.2
retired
0.31.1
0.31.0
0.30.1
0.30.0-rc.4
0.30.0-rc.3
0.30.0-rc.2
0.30.0-rc.1
0.30.0-rc.0
0.29.1
0.29.0
0.28.6
0.28.5
0.28.4
0.28.3
0.28.2
0.28.1
0.28.0
0.27.6
0.27.5
0.27.1
0.27.0
0.25.0
0.24.4
0.24.2
0.24.1
0.24.0
0.23.0
0.22.0
0.21.0
0.20.0
0.19.0
0.18.0
0.17.0
0.16.0
0.15.0
0.14.0
0.13.0
0.12.0
0.11.1
0.10.0
0.9.0
0.8.0
0.6.0
0.5.0
0.4.0
0.3.0
0.2.4
0.2.3
0.2.1
0.2.0
0.1.5
0.1.4
0.1.3
0.1.2
0.1.1
0.1.0
The JSON:API extension for the Ash Framework.
Current section
Files
Jump to
Current section
Files
documentation/topics/open-api.md
# Open API
## Use with Phoenix
To set up the Open API endpoints for your application, first include the `:open_api_spex` dependency:
```elixir
{:open_api_spex, "~> 3.16"},
```
Then in the module where you call `use AshJsonApi.Router` add the following option:
```elixir
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.
```elixir
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:
```elixir
{: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:
```elixir
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.
```elixir
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:
```elixir
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.