Skip to content

Commit 332b0d9

Browse files
tomkonidastomkonidas
authored
Add Documentation for Ratings API Endpoints (#366)
* Add Ratings API documentation * Use Signal as example App
1 parent 0288e74 commit 332b0d9

11 files changed

+218
-48
lines changed

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

+4-4
Original file line numberDiff line numberDiff line change
@@ -14,10 +14,10 @@ defmodule PlexusWeb.API.V1.AppController do
1414
operation :index,
1515
summary: "List Applications",
1616
parameters: [
17-
page: [in: :query, description: "Page number", type: :integer, example: 2],
17+
page: [in: :query, description: "Page number", type: :integer, example: 1],
1818
limit: [in: :query, description: "Max results per page", type: :integer, example: 25],
1919
scores: [in: :query, description: "Include scores", type: :boolean, example: true],
20-
q: [in: :query, description: "Search query", type: :string, example: "YouTube"]
20+
q: [in: :query, description: "Search query", type: :string, example: "Signal"]
2121
],
2222
responses: [
2323
ok: {"Applications", "application/json", AppsResponse}
@@ -55,12 +55,12 @@ defmodule PlexusWeb.API.V1.AppController do
5555
description: "App Package",
5656
type: :string,
5757
required: true,
58-
example: "com.google.android.youtube"
58+
example: "org.thoughtcrime.securesms"
5959
],
6060
scores: [in: :query, description: "Include scores", type: :boolean, example: true]
6161
],
6262
responses: [
63-
ok: {"Applications", "application/json", AppResponse}
63+
ok: {"Application", "application/json", AppResponse}
6464
]
6565

6666
def show(conn, %{"package" => package} = params) do

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

+46
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,33 @@
11
defmodule PlexusWeb.API.V1.RatingController do
22
use PlexusWeb, :controller
3+
use OpenApiSpex.ControllerSpecs
34

45
alias Plexus.Ratings
6+
alias PlexusWeb.API.V1.Schemas.RatingResponse
7+
alias PlexusWeb.API.V1.Schemas.RatingsResponse
58
alias PlexusWeb.Params
69

710
action_fallback PlexusWeb.FallbackController
811

12+
tags ["ratings"]
13+
14+
operation :index,
15+
summary: "List Application Ratings",
16+
parameters: [
17+
package: [
18+
in: :path,
19+
description: "App Package",
20+
type: :string,
21+
required: true,
22+
example: "org.thoughtcrime.securesms"
23+
],
24+
page: [in: :query, description: "Page number", type: :integer, example: 1],
25+
limit: [in: :query, description: "Max results per page", type: :integer, example: 5]
26+
],
27+
responses: [
28+
ok: {"Ratings", "application/json", RatingsResponse}
29+
]
30+
931
def index(conn, %{"package" => app_package} = params) do
1032
opts =
1133
[order_by: [desc: :app_build_number, desc: :updated_at]]
@@ -15,6 +37,8 @@ defmodule PlexusWeb.API.V1.RatingController do
1537
render(conn, :index, page: page)
1638
end
1739

40+
operation :create, false
41+
1842
def create(conn, %{"package" => app_package, "rating" => params}) do
1943
schema = %{
2044
android_version: {:string, [required: true]},
@@ -40,6 +64,28 @@ defmodule PlexusWeb.API.V1.RatingController do
4064
end
4165
end
4266

67+
operation :show,
68+
summary: "Get Application Rating",
69+
parameters: [
70+
package: [
71+
in: :path,
72+
description: "App Package",
73+
type: :string,
74+
required: true,
75+
example: "org.thoughtcrime.securesms"
76+
],
77+
id: [
78+
in: :path,
79+
description: "Rating Unique Identifier",
80+
type: :string,
81+
required: true,
82+
example: "72f5d88e-a467-4729-998f-db1edcfad6bc"
83+
]
84+
],
85+
responses: [
86+
ok: {"Rating", "application/json", RatingResponse}
87+
]
88+
4389
def show(conn, %{"id" => id}) do
4490
rating = Ratings.get_rating!(id)
4591
render(conn, :show, rating: rating)

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

+11-11
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
defmodule PlexusWeb.API.V1.Schemas.App do
22
alias OpenApiSpex.Schema
3-
alias PlexusWeb.API.V1.Schemas.Scores
3+
alias PlexusWeb.API.V1.Schemas.AverageScores
44
require OpenApiSpex
55

66
OpenApiSpex.schema(%{
@@ -11,27 +11,27 @@ defmodule PlexusWeb.API.V1.Schemas.App do
1111
name: %Schema{type: :string, description: "Name"},
1212
package: %Schema{type: :string, description: "App Package"},
1313
icon_url: %Schema{type: :string, description: "URL of Icon"},
14-
scores: Scores
14+
scores: AverageScores
1515
},
1616
example: %{
17-
"name" => "YouTube Music",
18-
"package" => "com.google.android.youtube.tvmusic",
17+
"name" => "Signal",
18+
"package" => "org.thoughtcrime.securesms",
1919
"scores" => %{
2020
"native" => %{
2121
"rating_type" => "native",
22-
"numerator" => 1.2,
23-
"total_count" => 21,
24-
"denominator" => 4
22+
"numerator" => 3.86,
23+
"denominator" => 4,
24+
"total_count" => 28
2525
},
2626
"micro_g" => %{
2727
"rating_type" => "micro_g",
28-
"numerator" => 4.0,
29-
"total_count" => 44,
30-
"denominator" => 4
28+
"numerator" => 3.92,
29+
"denominator" => 4,
30+
"total_count" => 25
3131
}
3232
},
3333
"icon_url" =>
34-
"https://play-lh.googleusercontent.com/76AjYITcB0dI0sFqdQjNgXQxRMlDIswbp0BAU_O5Oob-73b6cqKggVlAiNXQAW5Bl1g"
34+
"https://play-lh.googleusercontent.com/jCln_XT8Ruzp7loH1S6yM-ZzzpLP1kZ3CCdXVEo0tP2w5HNtWQds6lo6aLxLIjiW_X8"
3535
}
3636
})
3737
end

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

+10-10
Original file line numberDiff line numberDiff line change
@@ -4,32 +4,32 @@ defmodule PlexusWeb.API.V1.Schemas.AppResponse do
44

55
OpenApiSpex.schema(%{
66
title: "AppResponse",
7-
description: "Response schema for an application",
7+
description: "Response Schema for an Application",
88
type: :object,
99
properties: %{
1010
data: App
1111
},
1212
example: %{
1313
"data" => [
1414
%{
15-
"name" => "YouTube Music",
16-
"package" => "com.google.android.youtube.tvmusic",
15+
"name" => "Signal",
16+
"package" => "org.thoughtcrime.securesms",
1717
"scores" => %{
1818
"native" => %{
1919
"rating_type" => "native",
20-
"numerator" => 1.2,
21-
"total_count" => 21,
22-
"denominator" => 4
20+
"numerator" => 3.86,
21+
"denominator" => 4,
22+
"total_count" => 28
2323
},
2424
"micro_g" => %{
2525
"rating_type" => "micro_g",
26-
"numerator" => 3.9,
27-
"total_count" => 44,
28-
"denominator" => 4
26+
"numerator" => 3.92,
27+
"denominator" => 4,
28+
"total_count" => 25
2929
}
3030
},
3131
"icon_url" =>
32-
"https://play-lh.googleusercontent.com/lMoItBgdPPVDJsNOVtP26EKHePkwBg-PkuY9NOrc-fumRtTFP4XhpUNk_22syN4Datc"
32+
"https://play-lh.googleusercontent.com/jCln_XT8Ruzp7loH1S6yM-ZzzpLP1kZ3CCdXVEo0tP2w5HNtWQds6lo6aLxLIjiW_X8"
3333
}
3434
]
3535
}

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

+22
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
defmodule PlexusWeb.API.V1.Schemas.AppScore do
2+
alias OpenApiSpex.Schema
3+
require OpenApiSpex
4+
5+
OpenApiSpex.schema(%{
6+
title: "Score",
7+
description: "The Average Score of an App",
8+
type: :object,
9+
properties: %{
10+
rating_type: %Schema{type: :string, description: "Rating Type", enum: ["micro_g", "native"]},
11+
numenator: %Schema{type: :number, description: "Numenator"},
12+
denominator: %Schema{type: :integer, description: "Denominator"},
13+
total_count: %Schema{type: :string, description: "Total count of ratings"}
14+
},
15+
example: %{
16+
"numerator" => 4.0,
17+
"denominator" => 4,
18+
"rating_type" => "micro_g",
19+
"total_count" => 69
20+
}
21+
})
22+
end

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

+11-11
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ defmodule PlexusWeb.API.V1.Schemas.AppsResponse do
66

77
OpenApiSpex.schema(%{
88
title: "AppsResponse",
9-
description: "Response schema for a list of applications",
9+
description: "Response Schema for a List of Applications",
1010
type: :object,
1111
properties: %{
1212
data: %Schema{type: :array, items: App},
@@ -15,28 +15,28 @@ defmodule PlexusWeb.API.V1.Schemas.AppsResponse do
1515
example: %{
1616
"data" => [
1717
%{
18-
"name" => "YouTube Music",
19-
"package" => "com.google.android.youtube.tvmusic",
18+
"name" => "Signal",
19+
"package" => "org.thoughtcrime.securesms",
2020
"scores" => %{
2121
"native" => %{
2222
"rating_type" => "native",
23-
"numerator" => 1.1,
24-
"total_count" => 21,
25-
"denominator" => 4
23+
"numerator" => 3.86,
24+
"denominator" => 4,
25+
"total_count" => 28
2626
},
2727
"micro_g" => %{
2828
"rating_type" => "micro_g",
29-
"numerator" => 3.7,
30-
"total_count" => 43,
31-
"denominator" => 4
29+
"numerator" => 3.92,
30+
"denominator" => 4,
31+
"total_count" => 25
3232
}
3333
},
3434
"icon_url" =>
35-
"https://play-lh.googleusercontent.com/76AjYITcB0dI0sFqdQjNgXQxRMlDIswbp0BAU_O5Oob-73b6cqKggVlAiNXQAW5Bl1g"
35+
"https://play-lh.googleusercontent.com/jCln_XT8Ruzp7loH1S6yM-ZzzpLP1kZ3CCdXVEo0tP2w5HNtWQds6lo6aLxLIjiW_X8"
3636
}
3737
],
3838
"meta" => %{
39-
"page_number" => 3,
39+
"page_number" => 1,
4040
"limit" => 1,
4141
"total_count" => 420,
4242
"total_pages" => 69

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

+5-5
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,14 @@
1-
defmodule PlexusWeb.API.V1.Schemas.Scores do
2-
alias PlexusWeb.API.V1.Schemas.Score
1+
defmodule PlexusWeb.API.V1.Schemas.AverageScores do
2+
alias PlexusWeb.API.V1.Schemas.AppScore
33
require OpenApiSpex
44

55
OpenApiSpex.schema(%{
66
title: "Scores",
7-
description: "A Representation of Scores",
7+
description: "The Average Scores of an App",
88
type: :object,
99
properties: %{
10-
micro_g: Score,
11-
native: Score
10+
micro_g: AppScore,
11+
native: AppScore
1212
},
1313
derive?: false,
1414
example: %{

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

+37
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
defmodule PlexusWeb.API.V1.Schemas.Rating do
2+
alias OpenApiSpex.Schema
3+
alias PlexusWeb.API.V1.Schemas.Score
4+
require OpenApiSpex
5+
6+
OpenApiSpex.schema(%{
7+
title: "Rating",
8+
description: "A Representation of User Rating",
9+
type: :object,
10+
properties: %{
11+
id: %Schema{type: :string, description: "Unique Identifier"},
12+
android_version: %Schema{type: :string, description: "Android Version"},
13+
app_package: %Schema{type: :string, description: "App Package"},
14+
app_version: %Schema{type: :string, description: "App Version"},
15+
app_build_number: %Schema{type: :integer, description: "App Build Number"},
16+
rom_name: %Schema{type: :string, description: "ROM Name"},
17+
rom_build: %Schema{type: :string, description: "ROM Build"},
18+
installation_source: %Schema{type: :string, description: "Installation Source"},
19+
score: Score,
20+
notes: %Schema{type: :string, description: "Notes", nullable: true},
21+
rating_type: %Schema{type: :string, description: "Rating Type", enum: ["micro_g", "native"]}
22+
},
23+
example: %{
24+
"id" => "72f5d88e-a467-4729-998f-db1edcfad6bc",
25+
"app_version" => "7.15.4",
26+
"rating_type" => "native",
27+
"app_package" => "org.thoughtcrime.securesms",
28+
"score" => %{"numerator" => 4, "denominator" => 4},
29+
"android_version" => "14.0",
30+
"app_build_number" => 145_100,
31+
"installation_source" => "google_play_alternative",
32+
"notes" => nil,
33+
"rom_build" => "2024083100",
34+
"rom_name" => "GrapheneOS"
35+
}
36+
})
37+
end

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

+30
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
defmodule PlexusWeb.API.V1.Schemas.RatingResponse do
2+
alias PlexusWeb.API.V1.Schemas.Rating
3+
require OpenApiSpex
4+
5+
OpenApiSpex.schema(%{
6+
title: "RatingResponse",
7+
description: "Response Schema for a Rating",
8+
type: :object,
9+
properties: %{
10+
data: Rating
11+
},
12+
example: %{
13+
"data" => [
14+
%{
15+
"id" => "72f5d88e-a467-4729-998f-db1edcfad6bc",
16+
"app_version" => "7.15.4",
17+
"rating_type" => "native",
18+
"app_package" => "org.thoughtcrime.securesms",
19+
"score" => %{"numerator" => 4, "denominator" => 4},
20+
"android_version" => "14.0",
21+
"app_build_number" => 145_100,
22+
"installation_source" => "google_play_alternative",
23+
"notes" => nil,
24+
"rom_build" => "2024083100",
25+
"rom_name" => "GrapheneOS"
26+
}
27+
]
28+
}
29+
})
30+
end

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

+39
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
defmodule PlexusWeb.API.V1.Schemas.RatingsResponse do
2+
alias OpenApiSpex.Schema
3+
alias PlexusWeb.API.V1.Schemas.Page
4+
alias PlexusWeb.API.V1.Schemas.Rating
5+
require OpenApiSpex
6+
7+
OpenApiSpex.schema(%{
8+
title: "RatingsResponse",
9+
description: "Response Schema for a list of Ratings",
10+
type: :object,
11+
properties: %{
12+
data: %Schema{type: :array, items: Rating},
13+
meta: Page
14+
},
15+
example: %{
16+
"data" => [
17+
%{
18+
"id" => "72f5d88e-a467-4729-998f-db1edcfad6bc",
19+
"app_version" => "7.15.4",
20+
"rating_type" => "native",
21+
"app_package" => "org.thoughtcrime.securesms",
22+
"score" => %{"numerator" => 4, "denominator" => 4},
23+
"android_version" => "14.0",
24+
"app_build_number" => 145_100,
25+
"installation_source" => "google_play_alternative",
26+
"notes" => "Works great!",
27+
"rom_build" => "2024083100",
28+
"rom_name" => "GrapheneOS"
29+
}
30+
],
31+
"meta" => %{
32+
"page_number" => 3,
33+
"limit" => 1,
34+
"total_count" => 420,
35+
"total_pages" => 69
36+
}
37+
}
38+
})
39+
end

0 commit comments

Comments
 (0)