Compile time OpenAPI schema

[shikanime]

Since my last contribution, I have been experimenting on how to shift the specification build from the runtime to the compile time, keeping only utilities such as Swagger UI. The caching mechanism via the PutSpec is kind of unnatural in user space since an OpenAPI (should?) be static at compile time but have some kind of caching mechanism.

I know that the library used @doc annotations in the past, but I'm still wondering if the idea of using them alongside a Mix Compile Task to fetch every documentation using Config as configuration entrypoint such as:

# config/config.exs
config :open_api_spex,
  spec_manifest: "priv/static/openapi.json"

# mix.exs
defmodule FooWeb do
  # ...
  
  def project do
    [
      # ...
      openapi: openapi()
    ]
  end
  
  def openapi do
    [
      info: [
        title: "Foo web"
      ],
      servers: [
        OpenApiSpex.Phoenix.from_endpoint(FooWeb.Endpoint)
      ],
      paths: OpenApiSpex.Phoenix.from_router(FooWeb.Router)
    ]
  end
end

# lib/foo_web/controllers/bar_controller.ex
defmodule FooWeb.BarController
  # ....

  @doc title: :create
  @doc response: [
    ok: {"Some desc", "application/json", FooWeb.Bar.BarView}
  ]
  def create(...) do
    # ...
  end
end

And this compile command will output the static OpenAPI spec in the assets directory that will be use by the Swagger UI.

mix open_api_spex.compile

I was inspired by the recent esbuild library and hexdocs itself, do you think it is a good idea?

[mbuhot]

How about making it easier to load an api spec from file?

eg:

    plug PutApiSpec, file: "priv/static/openapi.json"

Then you can build the API spec ahead of time using the existing mix openapi.spec.json and use the result at runtime.

[shikanime]

I was thinking of further encouraging the user to use the Plug.Static directly as a means of distributing the OpenAPI specification. Which reuse present well known building block in the generated Phoenix application and feel way more transparent for the user ( •̀ ω •́ )y

[mbuhot]

In general I'd avoid this style of configuration:

# config/config.exs
config :open_api_spex,
  spec_manifest: "priv/static/openapi.json"

It assumes there is a single API, which is often not the case. Eg see the example from the phoenix_swagger docs:

config :my_app, :phoenix_swagger,
  swagger_files: %{
    "booking-api.json" => [router: MyApp.BookingRouter],
    "reports-api.json" => [router: MyApp.ReportsRouter],
    "admin-api.json" => [router: MyApp.AdminRouter]
  }

But even that isn't ideal as it assumes that each API is driven by a single router.

[shikanime]

How about putting this in the Mix.Project application configuration? Because it seems strange to put information about the application in the configurations, which is more technical configuration of the application/library:

def project do
  [
    openapi_specs: [
      booking: [
        info: [title: "Booking API"],
        path: "priv/static/booking-api.json",
        router: MyApp.BookingRouter
      ],
      reports: [
        info: [title: "Reports API"],
        path: "priv/static/reports-api.json",
        router: MyApp.ReportsRouter
      ],

      # ...
    ]
  ]
end

We could then generate the JSON specification if there is only one specification defined:

mix openapi.spec.json

and if there are several specifications to do so:

mix openapi.spec.json reports

Without the need to pass the name of the ApiSpec module as today.

[mbuhot]

The issues with @doc are

1. It isn't available at compile time (Provide an API to access documentation metadata at compile time elixir-lang/elixir#8095)
2. They're also not available at runtime in mix releases unless you disable stripping docs in beam files.

[shikanime]

Mhhh, I was aware of the problem, I thought we could access the documentation metadata from a Mix task using Mix.Task.run("compile") but that doesn't seem to be the case from my experiment.
That said the Code.fetch_docs/1 function obviously works in the IEx interactive console.