Add api specs (#217)

lib/wanderer_app_web/controllers/character_api_controller.ex

@@ -1,20 +1,47 @@
 defmodule WandererAppWeb.CharactersAPIController do
   @moduledoc """
   Exposes an endpoint for listing ALL characters in the database
-
-  Endpoint:
-    GET /api/characters
   """
 
   use WandererAppWeb, :controller
+  use OpenApiSpex.ControllerSpecs
   alias WandererApp.Api.Character
 
+  @characters_index_response_schema %OpenApiSpex.Schema{
+    type: :object,
+    properties: %{
+      data: %OpenApiSpex.Schema{
+        type: :array,
+        items: %OpenApiSpex.Schema{
+          type: :object,
+          properties: %{
+            id: %OpenApiSpex.Schema{type: :string},
+            eve_id: %OpenApiSpex.Schema{type: :string},
+            name: %OpenApiSpex.Schema{type: :string},
+            corporation_name: %OpenApiSpex.Schema{type: :string},
+            alliance_name: %OpenApiSpex.Schema{type: :string}
+          },
+          required: ["id", "eve_id", "name"]
+        }
+      }
+    },
+    required: ["data"]
+  }
+
   @doc """
   GET /api/characters
-
-  Lists ALL characters in the database
-  Returns an array of objects, each with `id`, `eve_id`, `name`, etc.
   """
+  @spec index(Plug.Conn.t(), map()) :: Plug.Conn.t()
+  operation :index,
+    summary: "List Characters",
+    description: "Lists ALL characters in the database.",
+    responses: [
+      ok: {
+        "List of characters",
+        "application/json",
+        @characters_index_response_schema
+      }
+    ]
   def index(conn, _params) do
     case WandererApp.Api.read(Character) do
       {:ok, characters} ->