Skip to content

Enhance OpenAPI documentation with prefix and security info #378

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Enhance OpenAPI documentation with prefix and security info #378

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 22 additions & 0 deletions documentation/topics/open-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,6 +74,7 @@ To customize the main values of the OpenAPI spec, a few options are available:
```elixir
use AshJsonApi.Router,
domains: [...],
prefix: "/api/v1",
open_api: "/open_api",
open_api_title: "Title",
open_api_version: "1.0.0",
Expand All @@ -82,6 +83,8 @@ To customize the main values of the OpenAPI spec, a few options are available:

If `:open_api_servers` is not specified, a default server is automatically derived from your app's Phoenix endpoint, as retrieved from inbound connections on the `open_api` HTTP route.

The `:prefix` is usually automatically inferred, but when generating files or using swaggerui you'll need to set it manually.
Copy link
Contributor

@zachdaniel zachdaniel Aug 31, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wonder if we should actually just fix that?

Copy link
Contributor

@zachdaniel zachdaniel Aug 31, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could you look into modifying the opts in the router? Something like this:

    opts =
      Keyword.put_new_lazy(opts, :prefix, fn ->
        conn.request_path
        |> Path.split()
        |> Enum.reverse()
        |> Enum.drop(Enum.count(conn.path_info))
        |> Enum.reverse()
        |> case do
          [] -> "/"
          paths -> Path.join(paths)
        end
      end)


In case an active connection is not available, for example when generating the OpenAPI spec via CLI, you can explicitely specify a reference to the Phoenix endpoint:

```elixir
Expand All @@ -107,6 +110,25 @@ To override any value in the OpenApi documentation you can use the `:modify_open
end
```

A common use case for modifying the open api spec is using a security scheme other that authBearer with a JWT token
which requires adding the SecurityScheme and specifying where it is used.

```elixir
def modify_open_api(spec, _, _) do
%{
spec
| components: %{spec.components | securitySchemes:
%{
"basicAuth" => %OpenApiSpex.SecurityScheme{
type: "http",
description: "Basic HTTP Authentication using username and password",
scheme: "basic"
}
}
}, security: [%{"basicAuth" => []}] }
end
```

## Generate spec files via CLI

You can write the OpenAPI spec file to disk using the Mix tasks provided by [OpenApiSpex](https://github.com/open-api-spex/open_api_spex).
Expand Down
Loading