Improve GraphQL documentation and cleanup API

Signed-off-by: Thomas Citharel <tcit@tcit.fr>

lib/graphql/schema/discussions/comment.ex

@@ -13,27 +13,43 @@ defmodule Mobilizon.GraphQL.Schema.Discussions.CommentType do
   object :comment do
     interfaces([:action_log_object])
     field(:id, :id, description: "Internal ID for this comment")
-    field(:uuid, :uuid)
-    field(:url, :string)
-    field(:local, :boolean)
-    field(:visibility, :comment_visibility)
-    field(:text, :string)
-    field(:primaryLanguage, :string)
+    field(:uuid, :uuid, description: "An UUID for this comment")
+    field(:url, :string, description: "Comment URL")
+    field(:local, :boolean, description: "Whether this comment is local or not")
+    field(:visibility, :comment_visibility, description: "The visibility for the comment")
+    field(:text, :string, description: "The comment body")
+    field(:primaryLanguage, :string, description: "The comment's primary language")
 
     field(:replies, list_of(:comment)) do
+      description("A list of replies to the comment")
       resolve(dataloader(Discussions))
     end
 
-    field(:total_replies, :integer)
-    field(:in_reply_to_comment, :comment, resolve: dataloader(Discussions))
-    field(:event, :event, resolve: dataloader(Events))
-    field(:origin_comment, :comment, resolve: dataloader(Discussions))
-    field(:threadLanguages, non_null(list_of(:string)))
-    field(:actor, :person, resolve: dataloader(Actors))
-    field(:inserted_at, :datetime)
-    field(:updated_at, :datetime)
-    field(:deleted_at, :datetime)
-    field(:published_at, :datetime)
+    field(:total_replies, :integer,
+      description: "The number of total known replies to this comment"
+    )
+
+    field(:in_reply_to_comment, :comment,
+      resolve: dataloader(Discussions),
+      description: "The comment this comment directly replies to"
+    )
+
+    field(:event, :event,
+      resolve: dataloader(Events),
+      description: "The eventual event this comment is under"
+    )
+
+    field(:origin_comment, :comment,
+      resolve: dataloader(Discussions),
+      description: "The original comment that started the thread this comment is in"
+    )
+
+    field(:threadLanguages, non_null(list_of(:string)), description: "The thread languages")
+    field(:actor, :person, resolve: dataloader(Actors), description: "The comment's author")
+    field(:inserted_at, :datetime, description: "When was the comment inserted in database")
+    field(:updated_at, :datetime, description: "When was the comment updated")
+    field(:deleted_at, :datetime, description: "When was the comment deleted")
+    field(:published_at, :datetime, description: "When was the comment published")
   end
 
   @desc "The list of visibility options for a comment"
@@ -49,6 +65,7 @@ defmodule Mobilizon.GraphQL.Schema.Discussions.CommentType do
     value(:invite, description: "visible only to people invited")
   end
 
+  @desc "A paginated list of comments"
   object :paginated_comment_list do
     field(:elements, list_of(:comment), description: "A list of comments")
     field(:total, :integer, description: "The total number of comments in the list")
@@ -57,7 +74,7 @@ defmodule Mobilizon.GraphQL.Schema.Discussions.CommentType do
   object :comment_queries do
     @desc "Get replies for thread"
     field :thread, type: list_of(:comment) do
-      arg(:id, :id)
+      arg(:id, non_null(:id), description: "The comment ID")
       resolve(&Comment.get_thread/3)
     end
   end
@@ -65,25 +82,24 @@ defmodule Mobilizon.GraphQL.Schema.Discussions.CommentType do
   object :comment_mutations do
     @desc "Create a comment"
     field :create_comment, type: :comment do
-      arg(:text, non_null(:string))
-      arg(:event_id, non_null(:id))
-      arg(:in_reply_to_comment_id, :id)
-      arg(:actor_id, non_null(:id))
+      arg(:text, non_null(:string), description: "The comment's body")
+      arg(:event_id, non_null(:id), description: "The event under which this comment is")
+      arg(:in_reply_to_comment_id, :id, description: "The comment ID this one replies to")
 
       resolve(&Comment.create_comment/3)
     end
 
     @desc "Update a comment"
     field :update_comment, type: :comment do
-      arg(:text, non_null(:string))
-      arg(:comment_id, non_null(:id))
+      arg(:text, non_null(:string), description: "The comment updated body")
+      arg(:comment_id, non_null(:id), description: "The comment ID")
 
       resolve(&Comment.update_comment/3)
     end
 
     @desc "Delete a single comment"
     field :delete_comment, type: :comment do
-      arg(:comment_id, non_null(:id))
+      arg(:comment_id, non_null(:id), description: "The comment ID")
 
       resolve(&Comment.delete_comment/3)
     end

lib/graphql/schema/discussions/discussion.ex

@@ -12,9 +12,9 @@ defmodule Mobilizon.GraphQL.Schema.Discussions.DiscussionType do
   @desc "A discussion"
   object :discussion do
     field(:id, :id, description: "Internal ID for this discussion")
-    field(:title, :string)
-    field(:slug, :string)
-    field(:last_comment, :comment)
+    field(:title, :string, description: "The title for this discussion")
+    field(:slug, :string, description: "The slug for the discussion")
+    field(:last_comment, :comment, description: "The last comment of the discussion")
 
     field :comments, :paginated_comment_list do
       arg(:page, :integer, default_value: 1)
@@ -23,22 +23,27 @@ defmodule Mobilizon.GraphQL.Schema.Discussions.DiscussionType do
       description("The comments for the discussion")
     end
 
-    field(:creator, :person, resolve: dataloader(Actors))
-    field(:actor, :actor, resolve: dataloader(Actors))
-    field(:inserted_at, :datetime)
-    field(:updated_at, :datetime)
+    field(:creator, :person,
+      resolve: dataloader(Actors),
+      description: "This discussions's creator"
+    )
+
+    field(:actor, :actor, resolve: dataloader(Actors), description: "This discussion's group")
+    field(:inserted_at, :datetime, description: "When was this discussion's created")
+    field(:updated_at, :datetime, description: "When was this discussion's updated")
   end
 
+  @desc "A paginated list of discussions"
   object :paginated_discussion_list do
     field(:elements, list_of(:discussion), description: "A list of discussion")
-    field(:total, :integer, description: "The total number of comments in the list")
+    field(:total, :integer, description: "The total number of discussions in the list")
   end
 
   object :discussion_queries do
     @desc "Get a discussion"
     field :discussion, type: :discussion do
-      arg(:id, :id)
-      arg(:slug, :string)
+      arg(:id, :id, description: "The discussion's ID")
+      arg(:slug, :string, description: "The discussion's slug")
       resolve(&Discussion.get_discussion/3)
     end
   end
@@ -46,36 +51,39 @@ defmodule Mobilizon.GraphQL.Schema.Discussions.DiscussionType do
   object :discussion_mutations do
     @desc "Create a discussion"
     field :create_discussion, type: :discussion do
-      arg(:title, non_null(:string))
-      arg(:text, non_null(:string))
-      arg(:actor_id, non_null(:id))
-      arg(:creator_id, non_null(:id))
+      arg(:title, non_null(:string), description: "The discussion's title")
+      arg(:text, non_null(:string), description: "The discussion's first comment body")
+      arg(:actor_id, non_null(:id), description: "The discussion's group ID")
 
       resolve(&Discussion.create_discussion/3)
     end
 
+    @desc "Reply to a discussion"
     field :reply_to_discussion, type: :discussion do
-      arg(:discussion_id, non_null(:id))
-      arg(:text, non_null(:string))
+      arg(:discussion_id, non_null(:id), description: "The discussion's ID")
+      arg(:text, non_null(:string), description: "The discussion's reply body")
       resolve(&Discussion.reply_to_discussion/3)
     end
 
+    @desc "Update a discussion"
     field :update_discussion, type: :discussion do
-      arg(:title, non_null(:string))
-      arg(:discussion_id, non_null(:id))
+      arg(:title, non_null(:string), description: "The updated discussion's title")
+      arg(:discussion_id, non_null(:id), description: "The discussion's ID")
       resolve(&Discussion.update_discussion/3)
     end
 
+    @desc "Delete a discussion"
     field :delete_discussion, type: :discussion do
-      arg(:discussion_id, non_null(:id))
+      arg(:discussion_id, non_null(:id), description: "The discussion's ID")
 
       resolve(&Discussion.delete_discussion/3)
     end
   end
 
   object :discussion_subscriptions do
+    @desc "Notify when a discussion changed"
     field :discussion_comment_changed, :discussion do
-      arg(:slug, non_null(:string))
+      arg(:slug, non_null(:string), description: "The discussion's slug")
 
       config(fn args, _ ->
         {:ok, topic: args.slug}