Support passing a %Reference{} as a response when doing controller specs

examples/phoenix_app/lib/phoenix_app_web/api_spec.ex

@@ -24,6 +24,14 @@ defmodule PhoenixAppWeb.ApiSpec do
               }
             }
           }
+        },
+        schemas: %{
+          responses: %{
+            unprocessable_entity: %Response{
+              description: "Unprocessable Entity",
+              content: %{"application/json" => %MediaType{schema: %Schema{type: :object}}}
+            }
+          }
         }
       },
       security: [

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

@@ -9,7 +9,7 @@ defmodule PhoenixAppWeb.UserController do
   use PhoenixAppWeb, :controller
   use OpenApiSpex.ControllerSpecs
 
-  alias OpenApiSpex.Schema
+  alias OpenApiSpex.{Schema, Reference}
   alias PhoenixApp.{Accounts, Accounts.User}
   alias PhoenixAppWeb.Schemas
 
@@ -23,6 +23,7 @@ defmodule PhoenixAppWeb.UserController do
     description: "List all users",
     responses: [
       ok: {"User List Response", "application/json", Schemas.UsersResponse}
+      unprocessable_entity: %Reference{"$ref": "#/components/responses/unprocessable_entity"},
     ]
 
   def index(conn, _params) do

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

@@ -5,7 +5,7 @@ defmodule PhoenixAppWeb.UserControllerWithStructSpecs do
   """
   use PhoenixAppWeb, :controller
   import OpenApiSpex.Operation, only: [parameter: 5, request_body: 4, response: 3]
-  alias OpenApiSpex.Operation
+  alias OpenApiSpex.{Operation, Reference}
   alias PhoenixApp.{Accounts, Accounts.User}
   alias PhoenixAppWeb.Schemas
 
@@ -36,6 +36,7 @@ defmodule PhoenixAppWeb.UserControllerWithStructSpecs do
       operationId: "UserController.index",
       responses: %{
         200 => response("User List Response", "application/json", Schemas.UsersResponse)
+        422 => %Reference{"$ref": "#/components/responses/unprocessable_entity"},
       }
     }
   end

lib/open_api_spex/operation_builder.ex

@@ -85,7 +85,7 @@ defmodule OpenApiSpex.OperationBuilder do
       {status, {description, mime, schema, opts}} ->
         {status_to_code(status), Operation.response(description, mime, schema, opts)}
 
-      {status, %Response{} = response} ->
+      {status, %struct{} = response} when struct in [Reference, Response] ->
         {status_to_code(status), response}
 
       {status, description} when is_binary(description) ->

test/controller_test.exs

@@ -42,6 +42,10 @@ defmodule OpenApiSpex.ControllerTest do
       assert %{responses: %{404 => _}} = @controller.open_api_operation(:update)
     end
 
+    test "has response as reference for HTTP 422" do
+      assert %{responses: %{422 => %Reference{}}} = @controller.open_api_operation(:update)
+    end
+
     test "has default response" do
       assert %{responses: %{:default => _}} = @controller.open_api_operation(:update)
     end

test/support/api_spec.ex

@@ -1,6 +1,5 @@
 defmodule OpenApiSpexTest.ApiSpec do
   alias OpenApiSpex.{
-    Components,
     Components,
     Contact,
     Info,
@@ -9,7 +8,9 @@ defmodule OpenApiSpexTest.ApiSpec do
     Parameter,
     Paths,
     Schema,
-    Server
+    Server,
+    Response,
+    MediaType
   }
 
   alias OpenApiSpexTest.{Router, Schemas}
@@ -73,6 +74,12 @@ defmodule OpenApiSpexTest.ApiSpec do
             required: true,
             example: 12
           }
+        },
+        responses: %{
+          unprocessable_entity: %Response{
+            description: "Unprocessable Entity",
+            content: %{"application/json" => %MediaType{schema: %Schema{type: :object}}}
+          }
         }
       },
       paths: Paths.from_router(Router)

test/support/user_controller_annotated.ex

@@ -2,7 +2,7 @@ defmodule OpenApiSpexTest.UserControllerAnnotated do
   @moduledoc tags: ["User"]
 
   use OpenApiSpex.Controller
-  alias OpenApiSpex.Header
+  alias OpenApiSpex.{Header, Reference}
   alias OpenApiSpexTest.Schemas.{GenericError, NotFound, Unauthorized, User}
 
   @doc """
@@ -27,6 +27,7 @@ defmodule OpenApiSpexTest.UserControllerAnnotated do
          },
          unauthorized: Unauthorized.response(),
          not_found: NotFound.response(),
+         unprocessable_entity: %Reference{"$ref": "#/components/responses/unprocessable_entity"},
          default: GenericError.response()
        ]
   @doc security: [%{"authorization" => []}]