Skip to content

Commit 356095c

Browse files
tomkonidastomkonidas
committed
Add Ratings API documentation
1 parent 0288e74 commit 356095c

File tree

8 files changed

+184
-14
lines changed

8 files changed

+184
-14
lines changed

‎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

+2-2
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,7 +11,7 @@ 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: %{
1717
"name" => "YouTube Music",

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

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

+3-7
Original file line numberDiff line numberDiff line change
@@ -7,16 +7,12 @@ defmodule PlexusWeb.API.V1.Schemas.Score do
77
description: "A Representation of a Score",
88
type: :object,
99
properties: %{
10-
rating_type: %Schema{type: :string, description: "Rating Type", enum: ["micro_g", "native"]},
11-
numerator: %Schema{type: :number, description: "Numerator"},
12-
denominator: %Schema{type: :integer, description: "Denominator"},
13-
total_count: %Schema{type: :string, description: "Total count of ratings"}
10+
numenator: %Schema{type: :number, description: "Numenator"},
11+
denominator: %Schema{type: :integer, description: "Denominator"}
1412
},
1513
example: %{
1614
"numerator" => 4.0,
17-
"denominator" => 4,
18-
"rating_type" => "micro_g",
19-
"total_count" => 69
15+
"denominator" => 4
2016
}
2117
})
2218
end

0 commit comments

Comments
 (0)