From 469f628f4405f483161200062f60dc7931041e53 Mon Sep 17 00:00:00 2001
From: Robert Graff <robert@workingdemo.com>
Date: Sun, 31 Aug 2025 12:53:13 -0700
Subject: [PATCH] Enhance OpenAPI documentation with prefix and security info

Added details about prefix and security scheme customization in OpenAPI spec.
---
 documentation/topics/open-api.md | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/documentation/topics/open-api.md b/documentation/topics/open-api.md
index 7340d3ff..5f8afd80 100644
--- a/documentation/topics/open-api.md
+++ b/documentation/topics/open-api.md
@@ -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",
@@ -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.
+
 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
@@ -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).