Support generating OpenAPI spec files with Mix tasks (#200)

* Chore: move OpenAPI spec generation from controller to OpenAPI module

We strive to be able to generate the OpenAPI spec with Mix commands, and
not only by querying an HTTP route.

As a preliminar step for further developments, move the spec generation
to the OpenAPI module in order to have a more reusable `spec` function
instead of having it tied to the controller.

Notes:
- Even though the OpenAPI module is not strictly related to HTTP
connections, the spec function accepts a `conn` argument since it was
already needed and provided to the `modify_open_api` function, if the
user specifies it in the opts. The `conn` argument is nil-able since we
want to support spec generation from the CLI.
- The OpenAPI title is now configurable with the `:open_api_title` opt.
- The OpenAPI version is now configurable with the `:open_api_version`
opt.
- The OpenAPI server list was previously populated by getting the
endpoint from a live `conn`. Since we want to support spec generation
from the CLI and without access to an active connection, a new option
`:phoenix_endpoint` is supported to statically provide a reference to
the endpoint. Another option `:open_api_servers` is added if the user
instead wants to specify a custom list of URLs.

Signed-off-by: Davide Briani <davide@briani.dev>

* Feat: add `spec/0` on Router to support OpenAPI generation via CLI

If OpenApiSpex is present, the `spec/0` function is exposed on the
Router.
This allows a user who has already configured AshJsonApi

```elixir
defmodule MyAppWeb.AshJsonApi
  use AshJsonApi.Router, domains: [...], open_api: "/open_api"
end
```

to directly generate the OpenAPI spec by running one the Mix tasks from
OpenApiSpex:

```sh
mix openapi.spec.json --spec MyAppWeb.AshJsonApi
mix openapi.spec.yaml --spec MyAppWeb.AshJsonApi
```

Signed-off-by: Davide Briani <davide@briani.dev>

* Doc: describe how to customize OpenAPI spec and generate via CLI

Add some details about the available options to customize the values of
the OpenAPI spec.
Add a section to describe how the spec files can be generated with Mix
tasks.

Signed-off-by: Davide Briani <davide@briani.dev>

* Doc: remove reference to `title` opt for OpenApiSpex.Plug.SwaggerUI

The option is not supported by OpenApiSpex.Plug.SwaggerUI and has no
effect.
To configure the title of the OpenAPI spec, a specific option has been
added on AshJsonApi.Router.

Signed-off-by: Davide Briani <davide@briani.dev>

---------

Signed-off-by: Davide Briani <davide@briani.dev>

Author: davidebriani

documentation/topics/open-api.md

@@ -20,7 +20,6 @@ Finally, you can use utilities provided by `open_api_spex` to show UIs for your
 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",
@@ -54,7 +53,6 @@ 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
   ]
 
@@ -71,6 +69,28 @@ Now you can go to `/api/swaggerui` and `/api/redoc`!
 
 ## Customize values in the OpenAPI documentation
 
+To customize the main values of the OpenAPI spec, a few options are available:
+
+```elixir
+  use AshJsonApi.Router,
+    domains: [...],
+    open_api: "/open_api",
+    open_api_title: "Title",
+    open_api_version: "1.0.0",
+    open_api_servers: ["http://domain.com/api/v1"]
+```
+
+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.
+
+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
+  use AshJsonApi.Router,
+    domains: [...],
+    open_api: "/open_api",
+    phoenix_endpoint: MyAppWeb.Endpoint
+```
+
 To override any value in the OpenApi documentation you can use the `:modify_open_api` options key:
 
 ```elixir
@@ -87,6 +107,35 @@ To override any value in the OpenApi documentation you can use the `:modify_open
   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).
+
+Supposing you have setup AshJsonApi as:
+
+```elixir
+defmodule MyAppWeb.AshJsonApi
+  use AshJsonApi.Router, domains: [...], open_api: "/open_api"
+end
+```
+
+you can generate the files with:
+
+```sh
+mix openapi.spec.json --spec MyAppWeb.AshJsonApi
+mix openapi.spec.yaml --spec MyAppWeb.AshJsonApi
+```
+
+To generate the YAML file you need to add the ymlr dependency.
+
+```elixir
+def deps do
+  [
+    {:ymlr, "~> 2.0"}
+  ]
+end
+```
+
 ## Known issues/limitations
 
 ### Swagger UI

lib/ash_json_api/controllers/open_api.ex

@@ -1,7 +1,5 @@
 if Code.ensure_loaded?(OpenApiSpex) do
   defmodule AshJsonApi.Controllers.OpenApi do
-    alias OpenApiSpex.{Info, OpenApi, SecurityScheme, Server}
-
     @moduledoc false
     def init(options) do
       options
@@ -19,60 +17,13 @@ if Code.ensure_loaded?(OpenApiSpex) do
       |> Plug.Conn.halt()
     end
 
-    defp modify(spec, conn, opts) do
-      case opts[:modify] do
-        modify when is_function(modify) ->
-          modify.(spec, conn, opts)
-
-        {m, f, a} ->
-          apply(m, f, [spec, conn, opts | a])
-
-        _ ->
-          spec
-      end
-    end
-
     @doc false
     def spec(conn, opts) do
-      domains = List.wrap(opts[:domain] || opts[:domains])
-
-      servers =
-        if conn.private[:phoenix_endpoint] do
-          [
-            Server.from_endpoint(conn.private.phoenix_endpoint)
-          ]
-        else
-          []
-        end
+      phoenix_endpoint = opts[:phoenix_endpoint] || conn[:private][:phoenix_endpoint]
 
-      %OpenApi{
-        info: %Info{
-          title: "Open API Specification",
-          version: "1.1"
-        },
-        servers: servers,
-        paths: AshJsonApi.OpenApi.paths(domains, domains),
-        tags: AshJsonApi.OpenApi.tags(domains),
-        components: %{
-          responses: AshJsonApi.OpenApi.responses(),
-          schemas: AshJsonApi.OpenApi.schemas(domains),
-          securitySchemes: %{
-            "api_key" => %SecurityScheme{
-              type: "apiKey",
-              description: "API Key provided in the Authorization header",
-              name: "api_key",
-              in: "header"
-            }
-          }
-        },
-        security: [
-          %{
-            # API Key security applies to all operations
-            "api_key" => []
-          }
-        ]
-      }
-      |> modify(conn, opts)
+      opts
+      |> Keyword.put(:phoenix_endpoint, phoenix_endpoint)
+      |> AshJsonApi.OpenApi.spec(conn)
     end
   end
 end

lib/ash_json_api/controllers/router.ex

@@ -37,9 +37,7 @@ defmodule AshJsonApi.Controllers.Router do
         AshJsonApi.Controllers.Schema.call(conn, domains: domains)
 
       open_api_request?(conn, open_api) ->
-        open_api_opts = open_api_opts(opts)
-
-        apply(AshJsonApi.Controllers.OpenApi, :call, [conn, open_api_opts])
+        apply(AshJsonApi.Controllers.OpenApi, :call, [conn, opts])
 
       conn.method == "GET" && Enum.any?(json_schema, &(&1 == conn.path_info)) ->
         AshJsonApi.Controllers.Schema.call(conn, opts)
@@ -89,12 +87,6 @@ defmodule AshJsonApi.Controllers.Router do
     end
   end
 
-  defp open_api_opts(opts) do
-    opts
-    |> Keyword.put(:modify, Keyword.get(opts, :modify_open_api))
-    |> Keyword.delete(:modify_open_api)
-  end
-
   defp open_api_request?(conn, open_api) do
     AshJsonApi.OpenApiSpexChecker.has_open_api?() && conn.method == "GET" &&
       Enum.any?(open_api, &(&1 == conn.path_info))

lib/ash_json_api/json_schema/open_api.ex

@@ -34,7 +34,9 @@ if Code.ensure_loaded?(OpenApiSpex) do
     alias Ash.Resource.{Actions, Relationships}
 
     alias OpenApiSpex.{
+      Info,
       MediaType,
+      OpenApi,
       Operation,
       Parameter,
       PathItem,
@@ -43,13 +45,75 @@ if Code.ensure_loaded?(OpenApiSpex) do
       RequestBody,
       Response,
       Schema,
+      SecurityScheme,
+      Server,
       Tag
     }
 
     @dialyzer {:nowarn_function, {:action_description, 3}}
     @dialyzer {:nowarn_function, {:relationship_resource_identifiers, 1}}
     @dialyzer {:nowarn_function, {:resource_object_schema, 1}}
 
+    def spec(opts \\ [], conn \\ nil) do
+      domains = List.wrap(opts[:domain] || opts[:domains])
+      title = opts[:open_api_title] || "Open API Specification"
+      version = opts[:open_api_version] || "1.1"
+
+      servers =
+        cond do
+          is_list(opts[:open_api_servers]) ->
+            Enum.map(opts[:open_api_servers], &%OpenApiSpex.Server{url: &1})
+
+          opts[:phoenix_endpoint] != nil ->
+            [Server.from_endpoint(opts[:phoenix_endpoint])]
+
+          true ->
+            []
+        end
+
+      %OpenApi{
+        info: %Info{
+          title: title,
+          version: version
+        },
+        servers: servers,
+        paths: AshJsonApi.OpenApi.paths(domains, domains),
+        tags: AshJsonApi.OpenApi.tags(domains),
+        components: %{
+          responses: AshJsonApi.OpenApi.responses(),
+          schemas: AshJsonApi.OpenApi.schemas(domains),
+          securitySchemes: %{
+            "api_key" => %SecurityScheme{
+              type: "apiKey",
+              description: "API Key provided in the Authorization header",
+              name: "api_key",
+              in: "header"
+            }
+          }
+        },
+        security: [
+          %{
+            # API Key security applies to all operations
+            "api_key" => []
+          }
+        ]
+      }
+      |> modify(conn, opts)
+    end
+
+    defp modify(spec, conn, opts) do
+      case opts[:modify_open_api] do
+        modify when is_function(modify) ->
+          modify.(spec, conn, opts)
+
+        {m, f, a} ->
+          apply(m, f, [spec, conn, opts | a])
+
+        _ ->
+          spec
+      end
+    end
+
     @doc """
     Common responses to include in the API Spec.
     """

lib/ash_json_api/router.ex

@@ -43,6 +43,12 @@ defmodule AshJsonApi.Router do
       end
 
       match(_, to: AshJsonApi.Controllers.Router, init_opts: Keyword.put(opts, :domains, domains))
+
+      if Code.ensure_loaded?(OpenApiSpex) do
+        def spec do
+          AshJsonApi.OpenApi.spec(unquote(opts))
+        end
+      end
     end
   end
 end

test/acceptance/open_api_test.exs

@@ -239,15 +239,15 @@ defmodule Test.Acceptance.OpenApiTest do
     end
   end
 
-  def modify(spec, _conn, _opts) do
+  def modify_open_api(spec, _conn, _opts) do
     %{spec | info: %{spec.info | title: "foobar"}}
   end
 
   setup do
     api_spec =
       AshJsonApi.Controllers.OpenApi.spec(%{private: %{}},
         domains: [Blogs],
-        modify: {__MODULE__, :modify, []}
+        modify_open_api: {__MODULE__, :modify_open_api, []}
       )
 
     %{open_api_spec: api_spec}