Add Documentation for Ratings API Endpoints

lib/plexus_web/controllers/api/v1/app_controller.ex

@@ -14,10 +14,10 @@ defmodule PlexusWeb.API.V1.AppController do
   operation :index,
     summary: "List Applications",
     parameters: [
-      page: [in: :query, description: "Page number", type: :integer, example: 2],
+      page: [in: :query, description: "Page number", type: :integer, example: 1],
       limit: [in: :query, description: "Max results per page", type: :integer, example: 25],
       scores: [in: :query, description: "Include scores", type: :boolean, example: true],
-      q: [in: :query, description: "Search query", type: :string, example: "YouTube"]
+      q: [in: :query, description: "Search query", type: :string, example: "Signal"]
     ],
     responses: [
       ok: {"Applications", "application/json", AppsResponse}
@@ -55,12 +55,12 @@ defmodule PlexusWeb.API.V1.AppController do
         description: "App Package",
         type: :string,
         required: true,
-        example: "com.google.android.youtube"
+        example: "org.thoughtcrime.securesms"
       ],
       scores: [in: :query, description: "Include scores", type: :boolean, example: true]
     ],
     responses: [
-      ok: {"Applications", "application/json", AppResponse}
+      ok: {"Application", "application/json", AppResponse}
     ]
 
   def show(conn, %{"package" => package} = params) do

lib/plexus_web/controllers/api/v1/rating_controller.ex

@@ -1,11 +1,33 @@
 defmodule PlexusWeb.API.V1.RatingController do
   use PlexusWeb, :controller
+  use OpenApiSpex.ControllerSpecs
 
   alias Plexus.Ratings
+  alias PlexusWeb.API.V1.Schemas.RatingResponse
+  alias PlexusWeb.API.V1.Schemas.RatingsResponse
   alias PlexusWeb.Params
 
   action_fallback PlexusWeb.FallbackController
 
+  tags ["ratings"]
+
+  operation :index,
+    summary: "List Application Ratings",
+    parameters: [
+      package: [
+        in: :path,
+        description: "App Package",
+        type: :string,
+        required: true,
+        example: "org.thoughtcrime.securesms"
+      ],
+      page: [in: :query, description: "Page number", type: :integer, example: 1],
+      limit: [in: :query, description: "Max results per page", type: :integer, example: 5]
+    ],
+    responses: [
+      ok: {"Ratings", "application/json", RatingsResponse}
+    ]
+
   def index(conn, %{"package" => app_package} = params) do
     opts =
       [order_by: [desc: :app_build_number, desc: :updated_at]]
@@ -15,6 +37,8 @@ defmodule PlexusWeb.API.V1.RatingController do
     render(conn, :index, page: page)
   end
 
+  operation :create, false
+
   def create(conn, %{"package" => app_package, "rating" => params}) do
     schema = %{
       android_version: {:string, [required: true]},
@@ -40,6 +64,28 @@ defmodule PlexusWeb.API.V1.RatingController do
     end
   end
 
+  operation :show,
+    summary: "Get Application Rating",
+    parameters: [
+      package: [
+        in: :path,
+        description: "App Package",
+        type: :string,
+        required: true,
+        example: "org.thoughtcrime.securesms"
+      ],
+      id: [
+        in: :path,
+        description: "Rating Unique Identifier",
+        type: :string,
+        required: true,
+        example: "72f5d88e-a467-4729-998f-db1edcfad6bc"
+      ]
+    ],
+    responses: [
+      ok: {"Rating", "application/json", RatingResponse}
+    ]
+
   def show(conn, %{"id" => id}) do
     rating = Ratings.get_rating!(id)
     render(conn, :show, rating: rating)

lib/plexus_web/controllers/api/v1/schemas/app.ex

@@ -1,6 +1,6 @@
 defmodule PlexusWeb.API.V1.Schemas.App do
   alias OpenApiSpex.Schema
-  alias PlexusWeb.API.V1.Schemas.Scores
+  alias PlexusWeb.API.V1.Schemas.AverageScores
   require OpenApiSpex
 
   OpenApiSpex.schema(%{
@@ -11,27 +11,27 @@ defmodule PlexusWeb.API.V1.Schemas.App do
       name: %Schema{type: :string, description: "Name"},
       package: %Schema{type: :string, description: "App Package"},
       icon_url: %Schema{type: :string, description: "URL of Icon"},
-      scores: Scores
+      scores: AverageScores
     },
     example: %{
-      "name" => "YouTube Music",
-      "package" => "com.google.android.youtube.tvmusic",
+      "name" => "Signal",
+      "package" => "org.thoughtcrime.securesms",
       "scores" => %{
         "native" => %{
           "rating_type" => "native",
-          "numerator" => 1.2,
-          "total_count" => 21,
-          "denominator" => 4
+          "numerator" => 3.86,
+          "denominator" => 4,
+          "total_count" => 28
         },
         "micro_g" => %{
           "rating_type" => "micro_g",
-          "numerator" => 4.0,
-          "total_count" => 44,
-          "denominator" => 4
+          "numerator" => 3.92,
+          "denominator" => 4,
+          "total_count" => 25
         }
       },
       "icon_url" =>
-        "https://play-lh.googleusercontent.com/76AjYITcB0dI0sFqdQjNgXQxRMlDIswbp0BAU_O5Oob-73b6cqKggVlAiNXQAW5Bl1g"
+        "https://play-lh.googleusercontent.com/jCln_XT8Ruzp7loH1S6yM-ZzzpLP1kZ3CCdXVEo0tP2w5HNtWQds6lo6aLxLIjiW_X8"
     }
   })
 end

lib/plexus_web/controllers/api/v1/schemas/app_response.ex

@@ -4,32 +4,32 @@ defmodule PlexusWeb.API.V1.Schemas.AppResponse do
 
   OpenApiSpex.schema(%{
     title: "AppResponse",
-    description: "Response schema for an application",
+    description: "Response Schema for an Application",
     type: :object,
     properties: %{
       data: App
     },
     example: %{
       "data" => [
         %{
-          "name" => "YouTube Music",
-          "package" => "com.google.android.youtube.tvmusic",
+          "name" => "Signal",
+          "package" => "org.thoughtcrime.securesms",
           "scores" => %{
             "native" => %{
               "rating_type" => "native",
-              "numerator" => 1.2,
-              "total_count" => 21,
-              "denominator" => 4
+              "numerator" => 3.86,
+              "denominator" => 4,
+              "total_count" => 28
             },
             "micro_g" => %{
               "rating_type" => "micro_g",
-              "numerator" => 3.9,
-              "total_count" => 44,
-              "denominator" => 4
+              "numerator" => 3.92,
+              "denominator" => 4,
+              "total_count" => 25
             }
           },
           "icon_url" =>
-            "https://play-lh.googleusercontent.com/lMoItBgdPPVDJsNOVtP26EKHePkwBg-PkuY9NOrc-fumRtTFP4XhpUNk_22syN4Datc"
+            "https://play-lh.googleusercontent.com/jCln_XT8Ruzp7loH1S6yM-ZzzpLP1kZ3CCdXVEo0tP2w5HNtWQds6lo6aLxLIjiW_X8"
         }
       ]
     }

lib/plexus_web/controllers/api/v1/schemas/app_score.ex

@@ -0,0 +1,22 @@
+defmodule PlexusWeb.API.V1.Schemas.AppScore do
+  alias OpenApiSpex.Schema
+  require OpenApiSpex
+
+  OpenApiSpex.schema(%{
+    title: "Score",
+    description: "The Average Score of an App",
+    type: :object,
+    properties: %{
+      rating_type: %Schema{type: :string, description: "Rating Type", enum: ["micro_g", "native"]},
+      numenator: %Schema{type: :number, description: "Numenator"},
+      denominator: %Schema{type: :integer, description: "Denominator"},
+      total_count: %Schema{type: :string, description: "Total count of ratings"}
+    },
+    example: %{
+      "numerator" => 4.0,
+      "denominator" => 4,
+      "rating_type" => "micro_g",
+      "total_count" => 69
+    }
+  })
+end

lib/plexus_web/controllers/api/v1/schemas/apps_response.ex

@@ -6,7 +6,7 @@ defmodule PlexusWeb.API.V1.Schemas.AppsResponse do
 
   OpenApiSpex.schema(%{
     title: "AppsResponse",
-    description: "Response schema for a list of applications",
+    description: "Response Schema for a List of Applications",
     type: :object,
     properties: %{
       data: %Schema{type: :array, items: App},
@@ -15,28 +15,28 @@ defmodule PlexusWeb.API.V1.Schemas.AppsResponse do
     example: %{
       "data" => [
         %{
-          "name" => "YouTube Music",
-          "package" => "com.google.android.youtube.tvmusic",
+          "name" => "Signal",
+          "package" => "org.thoughtcrime.securesms",
           "scores" => %{
             "native" => %{
               "rating_type" => "native",
-              "numerator" => 1.1,
-              "total_count" => 21,
-              "denominator" => 4
+              "numerator" => 3.86,
+              "denominator" => 4,
+              "total_count" => 28
             },
             "micro_g" => %{
               "rating_type" => "micro_g",
-              "numerator" => 3.7,
-              "total_count" => 43,
-              "denominator" => 4
+              "numerator" => 3.92,
+              "denominator" => 4,
+              "total_count" => 25
             }
           },
           "icon_url" =>
-            "https://play-lh.googleusercontent.com/76AjYITcB0dI0sFqdQjNgXQxRMlDIswbp0BAU_O5Oob-73b6cqKggVlAiNXQAW5Bl1g"
+            "https://play-lh.googleusercontent.com/jCln_XT8Ruzp7loH1S6yM-ZzzpLP1kZ3CCdXVEo0tP2w5HNtWQds6lo6aLxLIjiW_X8"
         }
       ],
       "meta" => %{
-        "page_number" => 3,
+        "page_number" => 1,
         "limit" => 1,
         "total_count" => 420,
         "total_pages" => 69

lib/plexus_web/controllers/api/v1/schemas/scores.ex → lib/plexus_web/controllers/api/v1/schemas/average_scores.ex

@@ -1,14 +1,14 @@
-defmodule PlexusWeb.API.V1.Schemas.Scores do
-  alias PlexusWeb.API.V1.Schemas.Score
+defmodule PlexusWeb.API.V1.Schemas.AverageScores do
+  alias PlexusWeb.API.V1.Schemas.AppScore
   require OpenApiSpex
 
   OpenApiSpex.schema(%{
     title: "Scores",
-    description: "A Representation of Scores",
+    description: "The Average Scores of an App",
     type: :object,
     properties: %{
-      micro_g: Score,
-      native: Score
+      micro_g: AppScore,
+      native: AppScore
     },
     derive?: false,
     example: %{

lib/plexus_web/controllers/api/v1/schemas/rating.ex

@@ -0,0 +1,37 @@
+defmodule PlexusWeb.API.V1.Schemas.Rating do
+  alias OpenApiSpex.Schema
+  alias PlexusWeb.API.V1.Schemas.Score
+  require OpenApiSpex
+
+  OpenApiSpex.schema(%{
+    title: "Rating",
+    description: "A Representation of User Rating",
+    type: :object,
+    properties: %{
+      id: %Schema{type: :string, description: "Unique Identifier"},
+      android_version: %Schema{type: :string, description: "Android Version"},
+      app_package: %Schema{type: :string, description: "App Package"},
+      app_version: %Schema{type: :string, description: "App Version"},
+      app_build_number: %Schema{type: :integer, description: "App Build Number"},
+      rom_name: %Schema{type: :string, description: "ROM Name"},
+      rom_build: %Schema{type: :string, description: "ROM Build"},
+      installation_source: %Schema{type: :string, description: "Installation Source"},
+      score: Score,
+      notes: %Schema{type: :string, description: "Notes", nullable: true},
+      rating_type: %Schema{type: :string, description: "Rating Type", enum: ["micro_g", "native"]}
+    },
+    example: %{
+      "id" => "72f5d88e-a467-4729-998f-db1edcfad6bc",
+      "app_version" => "7.15.4",
+      "rating_type" => "native",
+      "app_package" => "org.thoughtcrime.securesms",
+      "score" => %{"numerator" => 4, "denominator" => 4},
+      "android_version" => "14.0",
+      "app_build_number" => 145_100,
+      "installation_source" => "google_play_alternative",
+      "notes" => nil,
+      "rom_build" => "2024083100",
+      "rom_name" => "GrapheneOS"
+    }
+  })
+end

lib/plexus_web/controllers/api/v1/schemas/rating_response.ex

@@ -0,0 +1,30 @@
+defmodule PlexusWeb.API.V1.Schemas.RatingResponse do
+  alias PlexusWeb.API.V1.Schemas.Rating
+  require OpenApiSpex
+
+  OpenApiSpex.schema(%{
+    title: "RatingResponse",
+    description: "Response Schema for a Rating",
+    type: :object,
+    properties: %{
+      data: Rating
+    },
+    example: %{
+      "data" => [
+        %{
+          "id" => "72f5d88e-a467-4729-998f-db1edcfad6bc",
+          "app_version" => "7.15.4",
+          "rating_type" => "native",
+          "app_package" => "org.thoughtcrime.securesms",
+          "score" => %{"numerator" => 4, "denominator" => 4},
+          "android_version" => "14.0",
+          "app_build_number" => 145_100,
+          "installation_source" => "google_play_alternative",
+          "notes" => nil,
+          "rom_build" => "2024083100",
+          "rom_name" => "GrapheneOS"
+        }
+      ]
+    }
+  })
+end

lib/plexus_web/controllers/api/v1/schemas/ratings_response.ex

@@ -0,0 +1,39 @@
+defmodule PlexusWeb.API.V1.Schemas.RatingsResponse do
+  alias OpenApiSpex.Schema
+  alias PlexusWeb.API.V1.Schemas.Page
+  alias PlexusWeb.API.V1.Schemas.Rating
+  require OpenApiSpex
+
+  OpenApiSpex.schema(%{
+    title: "RatingsResponse",
+    description: "Response Schema for a list of Ratings",
+    type: :object,
+    properties: %{
+      data: %Schema{type: :array, items: Rating},
+      meta: Page
+    },
+    example: %{
+      "data" => [
+        %{
+          "id" => "72f5d88e-a467-4729-998f-db1edcfad6bc",
+          "app_version" => "7.15.4",
+          "rating_type" => "native",
+          "app_package" => "org.thoughtcrime.securesms",
+          "score" => %{"numerator" => 4, "denominator" => 4},
+          "android_version" => "14.0",
+          "app_build_number" => 145_100,
+          "installation_source" => "google_play_alternative",
+          "notes" => "Works great!",
+          "rom_build" => "2024083100",
+          "rom_name" => "GrapheneOS"
+        }
+      ],
+      "meta" => %{
+        "page_number" => 3,
+        "limit" => 1,
+        "total_count" => 420,
+        "total_pages" => 69
+      }
+    }
+  })
+end