Added documentations

Author: Wong-ZZ

lib/cadet/course/groups.ex

@@ -1,13 +1,29 @@
 defmodule Cadet.Course.Groups do
   use Cadet, [:context, :display]
 
+  import Cadet.Accounts
+
+  alias Cadet.Accounts.User
   alias Cadet.Course.Group
-  import Cadet.Accounts  
 
-  def get_group_overviews() do
-    Group
-    |> Repo.all()
-    |> Enum.map(fn group_info -> get_group_info(group_info) end)
+  @get_overviews_role ~w(staff admin)a
+
+  @doc """
+  Returns a list of groups containing information on the each group's id, avenger name and group name
+  """
+  @type group_overview :: %{id: integer, avenger_name: String.t, name: String.t}
+
+  @spec get_group_overviews(%User{}) :: [group_overview]
+  def get_group_overviews(_user = %User{role: role}) do
+    if role in @get_overviews_role do
+      overviews = 
+        Group
+        |> Repo.all()
+        |> Enum.map(fn group_info -> get_group_info(group_info) end)
+      {:ok, overviews}
+    else
+      {:error, {:unauthorised, "Unauthorised"}}
+    end
   end
 
   defp get_group_info(group_info) do

lib/cadet_web/controllers/group_controller.ex

@@ -6,8 +6,50 @@ defmodule CadetWeb.GroupController do
   alias Cadet.Course.Groups
 
   def index(conn, _) do
-    groups = Groups.get_group_overviews()
+    user = conn.assigns.current_user
+    result = Groups.get_group_overviews(user)
 
-    render(conn, "index.json", groups: groups)
+    case result do
+      {:ok, groups} ->
+        render(conn, "index.json", groups: groups)
+
+      {:error, {status, message}} ->
+        conn
+        |> put_status(status)
+        |> text(message)
+    end
+    
+  end
+
+  swagger_path :index do
+    get("/groups")
+
+    summary("Get a list of all the groups")
+
+    security([%{JWT: []}])
+
+    produces("application/json")
+
+    response(200, "OK", Schema.ref(:GroupsList))
+    response(401, "Unauthorised")
+  end
+
+  def swagger_definitions do
+    %{
+      GroupsList:
+        swagger_schema do
+          description("A list of all groups")
+          type(:array)
+          items(Schema.ref(:GroupOverview))
+        end,
+      GroupOverview:
+        swagger_schema do
+          properties do
+            id(:integer, "The group id", required: true)
+            avengerName(:string, "The name of the group's avenger", required: true)
+            groupName(:string, "The name of the group", required: true)
+          end
+        end
+    }
   end
 end