Add Ratings API documentation

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,7 +11,7 @@ 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",

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/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

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

@@ -7,16 +7,12 @@ defmodule PlexusWeb.API.V1.Schemas.Score do
     description: "A Representation of a Score",
     type: :object,
     properties: %{
-      rating_type: %Schema{type: :string, description: "Rating Type", enum: ["micro_g", "native"]},
-      numerator: %Schema{type: :number, description: "Numerator"},
-      denominator: %Schema{type: :integer, description: "Denominator"},
-      total_count: %Schema{type: :string, description: "Total count of ratings"}
+      numenator: %Schema{type: :number, description: "Numenator"},
+      denominator: %Schema{type: :integer, description: "Denominator"}
     },
     example: %{
       "numerator" => 4.0,
-      "denominator" => 4,
-      "rating_type" => "micro_g",
-      "total_count" => 69
+      "denominator" => 4
     }
   })
 end