Merge pull request #103 from open-api-spex/spec-behaviour

Add behaviour to OpenApi module documenting the `spec/0` callback.

Author: mbuhot

README.md

@@ -32,7 +32,9 @@ Start by adding an `ApiSpec` module to your application to populate an `OpenApiS
 ```elixir
 defmodule MyApp.ApiSpec do
   alias OpenApiSpex.{OpenApi, Server, Info, Paths}
+  @behaviour OpenApi
 
+  @impl OpenApi
   def spec do
     %OpenApi{
       servers: [

examples/phoenix_app/lib/phoenix_app_web/api_spec.ex

@@ -1,6 +1,8 @@
 defmodule PhoenixAppWeb.ApiSpec do
   alias OpenApiSpex.{Info, OpenApi, Paths}
+  @behaviour OpenApi
 
+  @impl OpenApi
   def spec do
     %OpenApi{
       info: %Info{
@@ -11,4 +13,4 @@ defmodule PhoenixAppWeb.ApiSpec do
     }
     |> OpenApiSpex.resolve_schema_modules()
   end
-end
+end

examples/phoenix_app/lib/phoenix_app_web/controllers/user_controller.ex

@@ -48,7 +48,7 @@ defmodule PhoenixAppWeb.UserController do
     }
   end
 
-  def create(conn = %{body_params: %Schemas.UserRequest{user: user_params}}, %{group_id: group_id}) do
+  def create(conn = %{body_params: %Schemas.UserRequest{user: user_params}}, %{group_id: _group_id}) do
     with {:ok, %User{} = user} <- Accounts.create_user(user_params) do
       conn
       |> put_status(:created)

examples/plug_app/lib/plug_app/api_spec.ex

@@ -1,6 +1,8 @@
 defmodule PlugApp.ApiSpec do
-  alias OpenApiSpex.{Info, OpenApi, Paths}
+  alias OpenApiSpex.{Info, OpenApi}
+  @behaviour OpenApi
 
+  @impl OpenApi
   def spec do
     %OpenApi{
       info: %Info{

lib/open_api_spex/open_api.ex

@@ -1,6 +1,7 @@
-defmodule OpenApiSpex.OpenApi do
+defmodule   OpenApiSpex.OpenApi do
   @moduledoc """
-  Defines the `OpenApiSpex.OpenApi.t` type.
+  Defines the `OpenApiSpex.OpenApi.t` type and the behaviour for application modules that
+  construct an `OpenApiSpex.OpenApi.t` at runtime.
   """
   alias OpenApiSpex.{
     Info, Server, Paths, Components,
@@ -35,6 +36,30 @@ defmodule OpenApiSpex.OpenApi do
     externalDocs: ExternalDocumentation.t | nil
   }
 
+  @doc """
+  A spec/0 callback function is required for use with the `OpenApiSpex.Plug.PutApiSpec` plug.
+
+  ## Example
+
+      @impl OpenApiSpex.OpenApi
+      def spec do
+        %OpenApi{
+          servers: [
+            # Populate the Server info from a phoenix endpoint
+            Server.from_endpoint(MyAppWeb.Endpoint, otp_app: :my_app)
+          ],
+          info: %Info{
+            title: "My App",
+            version: "1.0"
+          },
+          # populate the paths from a phoenix router
+          paths: Paths.from_router(MyAppWeb.Router)
+        }
+        |> OpenApiSpex.resolve_schema_modules() # discover request/response schemas from path specs
+      end
+  """
+  @callback spec() :: t
+
   @json_encoder Enum.find([Jason, Poison], &Code.ensure_loaded?/1)
 
   def json_encoder, do: @json_encoder

lib/open_api_spex/plug/put_api_spec.ex

@@ -4,6 +4,10 @@ defmodule OpenApiSpex.Plug.PutApiSpec do
 
   This allows downstream plugs to use the API spec for casting, validating and rendering.
 
+  ## Options
+
+   - module: A module implementing the `OpenApiSpex.OpenApi` behaviour
+
   ## Example
 
       plug OpenApiSpex.Plug.PutApiSpec, module: MyAppWeb.ApiSpec

test/operation2_test.exs

@@ -58,6 +58,9 @@ defmodule OpenApiSpex.Operation2Test do
   end
 
   defmodule SpecModule do
+    @behaviour OpenApiSpex.OpenApi
+
+    @impl OpenApiSpex.OpenApi
     def spec do
       paths = %{
         "/users" => %{

test/support/api_spec.ex

@@ -1,7 +1,9 @@
 defmodule OpenApiSpexTest.ApiSpec do
   alias OpenApiSpex.{OpenApi, Contact, License, Paths, Server, Info, Components}
   alias OpenApiSpexTest.{Router, Schemas}
+  @behaviour OpenApi
 
+  @impl OpenApi
   def spec() do
     %OpenApi{
       servers: [