Multiple Swagger files

[LuizFerK]

Hi, there. Love this lib, you guys are doing a nice job maintaining all this.

I'm migrating from OAS 2.0 to OAS 3.0 on my app and I wonder if there is a way to have multiples swagger (JSON) files, something like the config on Phoenix Swagger (lib that I use to OAS 2.0): https://hexdocs.pm/phoenix_swagger/getting-started.html#configuration

I have different contexts with the same routes on my app and need to keep it in separate swaggers (one for private, one for public, one for admin and goes on)

Thanks a lot!

[mbuhot]

Yes I think it should be possible.

If you define multiple top level API Definition modules https://github.com/open-api-spex/open_api_spex/blob/master/lib/open_api_spex/open_api.ex#L54-L69, then you can serve them at different paths and use them for validation/casting in your different router scopes.

pipeline :private_api do
  plug OpenApiSpex.Plug.PutApiSpec, module: MyAppWeb.PrivateApiSpec
  ... other plugs ...
end

pipeline :public_api do
  plug OpenApiSpex.Plug.PutApiSpec, module: MyAppWeb.PublicApiSpec
  ... other plugs ...
end

scope "/public/api" do
  pipe_through :public_api
  resources "/users", MyAppWeb.UserController, only: [:create, :index, :show]
  get "/openapi", OpenApiSpex.Plug.RenderSpec, []
end

scope "/private/api" do
  pipe_through :private_api
  resources "/admins", MyAppWeb.UserController, only: [:create, :index, :show]
  get "/openapi", OpenApiSpex.Plug.RenderSpec, []
end

[LuizFerK]

Got it! It kinda works, it creates multiple files, but now the paths and the schemas are being shared between the files (private routes show up on public docs and vice versa)

There's a way to limit it? I tried to use operation_spec but don't seem to be the right approach to this.

Also thanks for the fast reply! <3

[mbuhot]

To separate the operations between the APIs, you can either: a.) create separate routers for each API or b.) filter the output of Paths.from_router/1.

The filtering approach is probably the simplest:

def spec do
    %OpenApi{
      servers: [
        # Populate the Server info from a phoenix endpoint
        Server.from_endpoint(Endpoint)
      ],
      info: %Info{
        title: "My App",
        version: "1.0"
      },
      # Populate the paths from a phoenix router, filtering to only the `/api/private` routes 
      paths: 
        Router
        |> Paths.from_router() 
        |> Enum.filter(fn {path, _item} -> String.starts_with(path, "/api/private/" end) 
        |> Map.new()
    }
    |> OpenApiSpex.resolve_schema_modules() # Discover request/response schemas from path specs
  end

[LuizFerK]

This solution was the one that I'd been looking for! Thanks so much, @mbuhot , this solve my problem.

[axelson]

Thanks @mbuhot! That was very helpful! Here's a full version of a spec module with some minor typos fixed.

defmodule MyAppWeb.ApiSpecV1 do
  alias OpenApiSpex.Info
  alias OpenApiSpex.OpenApi
  alias OpenApiSpex.Paths
  alias OpenApiSpex.Server

  alias MyAppWeb.Endpoint
  alias MyAppWeb.Router

  def spec() do
    %OpenApi{
      servers: [
        Server.from_endpoint(Endpoint),
      ],
      info: %Info{
        title: "My App",
        version: "1.0",
      },
      paths:
        Paths.from_router(Router)
        |> Enum.filter(fn {path, _item} -> String.starts_with?(path, "/api/v1") end)
        |> Map.new(),
    }
    |> OpenApiSpex.resolve_schema_modules()
  end
end

[axelson]

Actually you'll likely want to not use Paths.from_router for this because you'll trigger the (2) behavior (from #272) for operations that you don't actually use which causes assertions/type/shape checking to fail. Instead you should filter on the Router.__routes__() before passing into Paths.from_routes.

defmodule MyAppWeb.ApiSpecV1 do
  alias OpenApiSpex.Info
  alias OpenApiSpex.OpenApi
  alias OpenApiSpex.Paths
  alias OpenApiSpex.Server

  alias MyAppWeb.Endpoint
  alias MyAppWeb.Router

  def spec() do
    %OpenApi{
      servers: [
        Server.from_endpoint(Endpoint),
      ],
      info: %Info{
        title: "My App",
        version: "1.0",
      },
      paths:
        Router.__routes__()
        |> Enum.filter(fn %{path: path} -> String.starts_with?(path, "/api/v2") end)
        |> Paths.from_routes(),
    }
    |> OpenApiSpex.resolve_schema_modules()
  end
end