Skip to content

Commit eff2912

Browse files
tomkonidastomkonidas
authored
Add Apps GET API documentation (#363)
1 parent 9dc09b1 commit eff2912

13 files changed

+266
-5
lines changed

‎.formatter.exs

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
[
2-
import_deps: [:ecto, :ecto_sql, :phoenix],
2+
import_deps: [:open_api_spex, :ecto, :ecto_sql, :phoenix],
33
subdirectories: ["priv/*/migrations"],
44
plugins: [Phoenix.LiveView.HTMLFormatter],
55
inputs: ["*.{heex,ex,exs}", "{config,lib,test}/**/*.{heex,ex,exs}", "priv/*/seeds.exs"]

‎config/dev.exs

+2
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,8 @@ config :plexus, Plexus.Repo,
1010
show_sensitive_data_on_connection_error: true,
1111
pool_size: 10
1212

13+
config :open_api_spex, :cache_adapter, OpenApiSpex.Plug.NoneCache
14+
1315
# For development, we disable any cache and enable
1416
# debugging and code reloading.
1517
#

‎lib/plexus_web/api_spec.ex

+17
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
defmodule PlexusWeb.ApiSpec do
2+
@behaviour OpenApiSpex.OpenApi
3+
4+
@impl OpenApiSpex.OpenApi
5+
def spec do
6+
OpenApiSpex.resolve_schema_modules(%OpenApiSpex.OpenApi{
7+
servers: [
8+
OpenApiSpex.Server.from_endpoint(PlexusWeb.Endpoint)
9+
],
10+
info: %OpenApiSpex.Info{
11+
title: "Plexus",
12+
version: to_string(Application.spec(:plexus, :vsn))
13+
},
14+
paths: OpenApiSpex.Paths.from_router(PlexusWeb.Router)
15+
})
16+
end
17+
end

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

+38
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,36 @@
11
defmodule PlexusWeb.API.V1.AppController do
22
use PlexusWeb, :controller
3+
use OpenApiSpex.ControllerSpecs
34

45
alias Plexus.Apps
6+
alias PlexusWeb.API.V1.Schemas.AppResponse
7+
alias PlexusWeb.API.V1.Schemas.AppsResponse
58
alias PlexusWeb.Params
69

710
action_fallback PlexusWeb.FallbackController
811

12+
tags ["apps"]
13+
14+
operation :index,
15+
summary: "List Applications",
16+
parameters: [
17+
page: [in: :query, description: "Page number", type: :integer, example: 2],
18+
limit: [in: :query, description: "Max results per page", type: :integer, example: 25],
19+
scores: [in: :query, description: "Include scores", type: :boolean, example: true],
20+
q: [in: :query, description: "Search query", type: :string, example: "YouTube"]
21+
],
22+
responses: [
23+
ok: {"Applications", "application/json", AppsResponse}
24+
]
25+
926
def index(conn, params) do
1027
opts = build_opts(params)
1128
page = Apps.list_apps(opts)
1229
render(conn, :index, page: page)
1330
end
1431

32+
operation :create, false
33+
1534
def create(conn, %{"app" => params}) do
1635
schema = %{
1736
package: {:string, required: true},
@@ -28,6 +47,22 @@ defmodule PlexusWeb.API.V1.AppController do
2847
end
2948
end
3049

50+
operation :show,
51+
summary: "Get Application",
52+
parameters: [
53+
package: [
54+
in: :path,
55+
description: "Android Package",
56+
type: :string,
57+
required: true,
58+
example: "com.google.android.youtube"
59+
],
60+
scores: [in: :query, description: "Include scores", type: :boolean, example: true]
61+
],
62+
responses: [
63+
ok: {"Applications", "application/json", AppResponse}
64+
]
65+
3166
def show(conn, %{"package" => package} = params) do
3267
opts = build_opts(params)
3368
app = Apps.get_app!(package, opts)
@@ -36,6 +71,9 @@ defmodule PlexusWeb.API.V1.AppController do
3671

3772
defp build_opts(params) do
3873
Enum.reduce(params, [], fn
74+
{"q", search_term}, acc ->
75+
Keyword.put(acc, :search_term, search_term)
76+
3977
{"scores", "true"}, acc ->
4078
Keyword.put(acc, :scores, true)
4179

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

+37
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
defmodule PlexusWeb.API.V1.Schemas.App do
2+
alias OpenApiSpex.Schema
3+
alias PlexusWeb.API.V1.Schemas.Scores
4+
require OpenApiSpex
5+
6+
OpenApiSpex.schema(%{
7+
title: "App",
8+
description: "A Representation of an App",
9+
type: :object,
10+
properties: %{
11+
name: %Schema{type: :string, description: "Name"},
12+
package: %Schema{type: :string, description: "Android Package"},
13+
icon_url: %Schema{type: :string, description: "URL of Icon"},
14+
scores: Scores
15+
},
16+
example: %{
17+
"name" => "YouTube Music",
18+
"package" => "com.google.android.youtube.tvmusic",
19+
"scores" => %{
20+
"native" => %{
21+
"rating_type" => "native",
22+
"numerator" => 1.2,
23+
"total_count" => 21,
24+
"denominator" => 4
25+
},
26+
"micro_g" => %{
27+
"rating_type" => "micro_g",
28+
"numerator" => 4.0,
29+
"total_count" => 44,
30+
"denominator" => 4
31+
}
32+
},
33+
"icon_url" =>
34+
"https://play-lh.googleusercontent.com/76AjYITcB0dI0sFqdQjNgXQxRMlDIswbp0BAU_O5Oob-73b6cqKggVlAiNXQAW5Bl1g"
35+
}
36+
})
37+
end

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

+37
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
defmodule PlexusWeb.API.V1.Schemas.AppResponse do
2+
alias PlexusWeb.API.V1.Schemas.App
3+
require OpenApiSpex
4+
5+
OpenApiSpex.schema(%{
6+
title: "AppResponse",
7+
description: "Response schema for an application",
8+
type: :object,
9+
properties: %{
10+
data: App
11+
},
12+
example: %{
13+
"data" => [
14+
%{
15+
"name" => "YouTube Music",
16+
"package" => "com.google.android.youtube.tvmusic",
17+
"scores" => %{
18+
"native" => %{
19+
"rating_type" => "native",
20+
"numerator" => 1.2,
21+
"total_count" => 21,
22+
"denominator" => 4
23+
},
24+
"micro_g" => %{
25+
"rating_type" => "micro_g",
26+
"numerator" => 3.9,
27+
"total_count" => 44,
28+
"denominator" => 4
29+
}
30+
},
31+
"icon_url" =>
32+
"https://play-lh.googleusercontent.com/lMoItBgdPPVDJsNOVtP26EKHePkwBg-PkuY9NOrc-fumRtTFP4XhpUNk_22syN4Datc"
33+
}
34+
]
35+
}
36+
})
37+
end

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

+46
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
defmodule PlexusWeb.API.V1.Schemas.AppsResponse do
2+
alias OpenApiSpex.Schema
3+
alias PlexusWeb.API.V1.Schemas.App
4+
alias PlexusWeb.API.V1.Schemas.Page
5+
require OpenApiSpex
6+
7+
OpenApiSpex.schema(%{
8+
title: "AppsResponse",
9+
description: "Response schema for a list of applications",
10+
type: :object,
11+
properties: %{
12+
data: %Schema{type: :array, items: App},
13+
meta: Page
14+
},
15+
example: %{
16+
"data" => [
17+
%{
18+
"name" => "YouTube Music",
19+
"package" => "com.google.android.youtube.tvmusic",
20+
"scores" => %{
21+
"native" => %{
22+
"rating_type" => "native",
23+
"numerator" => 1.1,
24+
"total_count" => 21,
25+
"denominator" => 4
26+
},
27+
"micro_g" => %{
28+
"rating_type" => "micro_g",
29+
"numerator" => 3.7,
30+
"total_count" => 43,
31+
"denominator" => 4
32+
}
33+
},
34+
"icon_url" =>
35+
"https://play-lh.googleusercontent.com/76AjYITcB0dI0sFqdQjNgXQxRMlDIswbp0BAU_O5Oob-73b6cqKggVlAiNXQAW5Bl1g"
36+
}
37+
],
38+
"meta" => %{
39+
"page_number" => 3,
40+
"limit" => 1,
41+
"total_count" => 420,
42+
"total_pages" => 69
43+
}
44+
}
45+
})
46+
end

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

+22
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
defmodule PlexusWeb.API.V1.Schemas.Page do
2+
alias OpenApiSpex.Schema
3+
require OpenApiSpex
4+
5+
OpenApiSpex.schema(%{
6+
title: "Page",
7+
description: "Page metadata",
8+
type: :object,
9+
properties: %{
10+
page_number: %Schema{type: :integer, description: "Current page number", default: 1},
11+
limit: %Schema{type: :integer, description: "Max results per page", default: 25},
12+
total_count: %Schema{type: :integer, description: "Total count of results", readOnly: true},
13+
total_pages: %Schema{type: :integer, description: "Total count of pages", readOnly: true}
14+
},
15+
example: %{
16+
"page_number" => 3,
17+
"limit" => 25,
18+
"total_count" => 420,
19+
"total_pages" => 69
20+
}
21+
})
22+
end

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

+22
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
defmodule PlexusWeb.API.V1.Schemas.Score do
2+
alias OpenApiSpex.Schema
3+
require OpenApiSpex
4+
5+
OpenApiSpex.schema(%{
6+
title: "Score",
7+
description: "A Representation of a Score",
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

+29
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
defmodule PlexusWeb.API.V1.Schemas.Scores do
2+
alias PlexusWeb.API.V1.Schemas.Score
3+
require OpenApiSpex
4+
5+
OpenApiSpex.schema(%{
6+
title: "Scores",
7+
description: "A Representation of Scores",
8+
type: :object,
9+
properties: %{
10+
micro_g: Score,
11+
native: Score
12+
},
13+
derive?: false,
14+
example: %{
15+
"micro_g" => %{
16+
"numerator" => 4.0,
17+
"denominator" => 4,
18+
"rating_type" => "micro_g",
19+
"total_count" => 69
20+
},
21+
"native" => %{
22+
"numerator" => 3.7,
23+
"denominator" => 4,
24+
"rating_type" => "native",
25+
"total_count" => 69
26+
}
27+
}
28+
})
29+
end

‎lib/plexus_web/router.ex

+9-2
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ defmodule PlexusWeb.Router do
1212

1313
pipeline :api do
1414
plug :accepts, ["json"]
15+
plug OpenApiSpex.Plug.PutApiSpec, module: PlexusWeb.ApiSpec
1516
end
1617

1718
pipeline :authenticated_device do
@@ -22,10 +23,11 @@ defmodule PlexusWeb.Router do
2223
plug :auth
2324
end
2425

25-
scope "/", PlexusWeb do
26+
scope "/" do
2627
pipe_through :browser
2728

28-
live "/", AppLive.Index, :index
29+
live "/", PlexusWeb.AppLive.Index, :index
30+
get "/swaggerui", OpenApiSpex.Plug.SwaggerUI, path: "/api/openapi"
2931
end
3032

3133
scope "/admin", PlexusWeb.Admin do
@@ -41,6 +43,11 @@ defmodule PlexusWeb.Router do
4143
live "/apps/:package/ratings/:rating_type", RatingLive.Index, :index
4244
end
4345

46+
scope "/api" do
47+
pipe_through :api
48+
get "/openapi", OpenApiSpex.Plug.RenderSpec, []
49+
end
50+
4451
scope "/api/v1", PlexusWeb.API.V1 do
4552
pipe_through :api
4653

‎mix.exs

+4-2
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ defmodule Plexus.MixProject do
44
def project do
55
[
66
app: :plexus,
7-
version: "0.1.0",
7+
version: "1.0.0",
88
elixir: "~> 1.15",
99
elixirc_paths: elixirc_paths(Mix.env()),
1010
start_permanent: Mix.env() == :prod,
@@ -59,7 +59,9 @@ defmodule Plexus.MixProject do
5959
{:plug_cowboy, "~> 2.6"},
6060
{:swoosh, "~> 1.3"},
6161
{:gen_smtp, "~> 1.2"},
62-
{:finch, "~> 0.13"}
62+
{:finch, "~> 0.13"},
63+
{:open_api_spex, "~> 3.20"},
64+
{:ymlr, "~> 5.1"}
6365
]
6466
end
6567

‎mix.lock

+2
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@
2626
"nimble_options": {:hex, :nimble_options, "1.1.1", "e3a492d54d85fc3fd7c5baf411d9d2852922f66e69476317787a7b2bb000a61b", [:mix], [], "hexpm", "821b2470ca9442c4b6984882fe9bb0389371b8ddec4d45a9504f00a66f650b44"},
2727
"nimble_pool": {:hex, :nimble_pool, "1.1.0", "bf9c29fbdcba3564a8b800d1eeb5a3c58f36e1e11d7b7fb2e084a643f645f06b", [:mix], [], "hexpm", "af2e4e6b34197db81f7aad230c1118eac993acc0dae6bc83bac0126d4ae0813a"},
2828
"nimble_totp": {:hex, :nimble_totp, "1.0.0", "79753bae6ce59fd7cacdb21501a1dbac249e53a51c4cd22b34fa8438ee067283", [:mix], [], "hexpm", "6ce5e4c068feecdb782e85b18237f86f66541523e6bad123e02ee1adbe48eda9"},
29+
"open_api_spex": {:hex, :open_api_spex, "3.20.1", "ce5b3db013cd7337ab147f39fa2d4d627ddeeb4ff3fea34792f43d7e2e654605", [:mix], [{:jason, "~> 1.0", [hex: :jason, repo: "hexpm", optional: true]}, {:plug, "~> 1.7", [hex: :plug, repo: "hexpm", optional: false]}, {:poison, "~> 3.0 or ~> 4.0 or ~> 5.0 or ~> 6.0", [hex: :poison, repo: "hexpm", optional: true]}, {:ymlr, "~> 2.0 or ~> 3.0 or ~> 4.0 or ~> 5.0", [hex: :ymlr, repo: "hexpm", optional: true]}], "hexpm", "dc9c383949d0fc4b20b73103ac20af39dad638b3a15c0e6281853c2fc7cc3cc8"},
2930
"phoenix": {:hex, :phoenix, "1.7.14", "a7d0b3f1bc95987044ddada111e77bd7f75646a08518942c72a8440278ae7825", [:mix], [{:castore, ">= 0.0.0", [hex: :castore, repo: "hexpm", optional: false]}, {:jason, "~> 1.0", [hex: :jason, repo: "hexpm", optional: true]}, {:phoenix_pubsub, "~> 2.1", [hex: :phoenix_pubsub, repo: "hexpm", optional: false]}, {:phoenix_template, "~> 1.0", [hex: :phoenix_template, repo: "hexpm", optional: false]}, {:phoenix_view, "~> 2.0", [hex: :phoenix_view, repo: "hexpm", optional: true]}, {:plug, "~> 1.14", [hex: :plug, repo: "hexpm", optional: false]}, {:plug_cowboy, "~> 2.7", [hex: :plug_cowboy, repo: "hexpm", optional: true]}, {:plug_crypto, "~> 1.2 or ~> 2.0", [hex: :plug_crypto, repo: "hexpm", optional: false]}, {:telemetry, "~> 0.4 or ~> 1.0", [hex: :telemetry, repo: "hexpm", optional: false]}, {:websock_adapter, "~> 0.5.3", [hex: :websock_adapter, repo: "hexpm", optional: false]}], "hexpm", "c7859bc56cc5dfef19ecfc240775dae358cbaa530231118a9e014df392ace61a"},
3031
"phoenix_ecto": {:hex, :phoenix_ecto, "4.6.2", "3b83b24ab5a2eb071a20372f740d7118767c272db386831b2e77638c4dcc606d", [:mix], [{:ecto, "~> 3.5", [hex: :ecto, repo: "hexpm", optional: false]}, {:phoenix_html, "~> 2.14.2 or ~> 3.0 or ~> 4.1", [hex: :phoenix_html, repo: "hexpm", optional: true]}, {:plug, "~> 1.9", [hex: :plug, repo: "hexpm", optional: false]}, {:postgrex, "~> 0.16 or ~> 1.0", [hex: :postgrex, repo: "hexpm", optional: true]}], "hexpm", "3f94d025f59de86be00f5f8c5dd7b5965a3298458d21ab1c328488be3b5fcd59"},
3132
"phoenix_html": {:hex, :phoenix_html, "4.1.1", "4c064fd3873d12ebb1388425a8f2a19348cef56e7289e1998e2d2fa758aa982e", [:mix], [], "hexpm", "f2f2df5a72bc9a2f510b21497fd7d2b86d932ec0598f0210fed4114adc546c6f"},
@@ -49,4 +50,5 @@
4950
"thousand_island": {:hex, :thousand_island, "1.3.5", "6022b6338f1635b3d32406ff98d68b843ba73b3aa95cfc27154223244f3a6ca5", [:mix], [{:telemetry, "~> 0.4 or ~> 1.0", [hex: :telemetry, repo: "hexpm", optional: false]}], "hexpm", "2be6954916fdfe4756af3239fb6b6d75d0b8063b5df03ba76fd8a4c87849e180"},
5051
"websock": {:hex, :websock, "0.5.3", "2f69a6ebe810328555b6fe5c831a851f485e303a7c8ce6c5f675abeb20ebdadc", [:mix], [], "hexpm", "6105453d7fac22c712ad66fab1d45abdf049868f253cf719b625151460b8b453"},
5152
"websock_adapter": {:hex, :websock_adapter, "0.5.6", "0437fe56e093fd4ac422de33bf8fc89f7bc1416a3f2d732d8b2c8fd54792fe60", [:mix], [{:bandit, ">= 0.6.0", [hex: :bandit, repo: "hexpm", optional: true]}, {:plug, "~> 1.14", [hex: :plug, repo: "hexpm", optional: false]}, {:plug_cowboy, "~> 2.6", [hex: :plug_cowboy, repo: "hexpm", optional: true]}, {:websock, "~> 0.5", [hex: :websock, repo: "hexpm", optional: false]}], "hexpm", "e04378d26b0af627817ae84c92083b7e97aca3121196679b73c73b99d0d133ea"},
53+
"ymlr": {:hex, :ymlr, "5.1.3", "a8061add5a378e20272a31905be70209a5680fdbe0ad51f40cb1af4bdd0a010b", [:mix], [], "hexpm", "8663444fa85101a117887c170204d4c5a2182567e5f84767f0071cf15f2efb1e"},
5254
}

0 commit comments

Comments
 (0)