From a2d26df17b5252253d23441af4f2157159da1e97 Mon Sep 17 00:00:00 2001 From: Anna Buianova Date: Tue, 10 Jan 2023 15:01:22 +0300 Subject: [PATCH] [API V1 docs] Podcast Episodes (#18908) * Podcast episodes api swagger docs (start) * Podcast Episodes api swagger docs * Fixed wording Co-authored-by: Ridhwana * Fixed wording Co-authored-by: Ridhwana * Removed commented code Co-authored-by: Ridhwana --- .../api/v1/docs/podcast_episodes_spec.rb | 63 ++++++++++++ spec/swagger_helper.rb | 25 ++++- swagger/v1/api_v1.json | 98 +++++++++++++++++++ 3 files changed, 185 insertions(+), 1 deletion(-) create mode 100644 spec/requests/api/v1/docs/podcast_episodes_spec.rb diff --git a/spec/requests/api/v1/docs/podcast_episodes_spec.rb b/spec/requests/api/v1/docs/podcast_episodes_spec.rb new file mode 100644 index 000000000..bdf59f25f --- /dev/null +++ b/spec/requests/api/v1/docs/podcast_episodes_spec.rb @@ -0,0 +1,63 @@ +require "rails_helper" +require "swagger_helper" + +# rubocop:disable RSpec/EmptyExampleGroup +# rubocop:disable RSpec/VariableName + +RSpec.describe "Api::V1::Docs::PodcastEpisodes" do + let(:Accept) { "application/vnd.forem.api-v1+json" } + let!(:podcast) { create(:podcast, slug: "codenewbie") } + + before { create(:podcast_episode, podcast: podcast) } + + describe "GET /podcast_episodes" do + path "/api/podcast_episodes" do + get "Podcast Episodes" do + security [] + tags "podcast_episodes" + description(<<-DESCRIBE.strip) + This endpoint allows the client to retrieve a list of podcast episodes. + "Podcast episodes" are episodes belonging to podcasts. + It will only return active (reachable) podcast episodes that belong to published podcasts available on the platform, ordered by descending publication date. + It supports pagination, each page will contain 30 articles by default. + DESCRIBE + operationId "getPodcastEpisodes" + produces "application/json" + parameter "$ref": "#/components/parameters/pageParam" + parameter "$ref": "#/components/parameters/perPageParam30to1000" + parameter name: :username, in: :query, required: false, + description: "Using this parameter will retrieve episodes belonging to a specific podcast.", + schema: { type: :string }, + example: "codenewbie" + + response "200", "A List of Podcast episodes" do + let(:"api-key") { nil } + schema type: :array, + items: { "$ref": "#/components/schemas/PodcastEpisodeIndex" } + add_examples + + run_test! + end + + response "200", "A List of Podcast episodes filtered by username" do + let(:username) { "codenewbie" } + schema type: :array, + items: { "$ref": "#/components/schemas/PodcastEpisodeIndex" } + add_examples + + run_test! + end + + response "404", "Unknown Podcast username" do + let(:username) { "unknown" } + add_examples + + run_test! + end + end + end + end +end + +# rubocop:enable RSpec/EmptyExampleGroup +# rubocop:enable RSpec/VariableName diff --git a/spec/swagger_helper.rb b/spec/swagger_helper.rb index 40c6560af..e599d7836 100644 --- a/spec/swagger_helper.rb +++ b/spec/swagger_helper.rb @@ -166,7 +166,7 @@ The default maximum value can be overridden by \"API_PER_PAGE_MAX\" environment } }, ArticleIndex: { - description: "Resprentation of an article or post returned in a list", + description: "Representation of an article or post returned in a list", type: :object, properties: { type_of: { type: :string }, @@ -204,6 +204,20 @@ The default maximum value can be overridden by \"API_PER_PAGE_MAX\" environment crossposted_at published_at last_comment_at published_timestamp user reading_time_minutes] }, + PodcastEpisodeIndex: { + description: "Representation of a podcast episode returned in a list", + type: :object, + properties: { + type_of: { type: :string }, + id: { type: :integer, format: :int32 }, + class_name: { type: :string }, + path: { type: :string, format: "path" }, + title: { type: :string }, + image_url: { description: "Podcast episode image url or podcast image url", type: :string, format: :url }, + podcast: { "$ref": "#/components/schemas/SharedPodcast" } + }, + required: %w[type_of class_name id path title image_url podcast] + }, SharedUser: { description: "The resource creator", type: "object", @@ -227,6 +241,15 @@ The default maximum value can be overridden by \"API_PER_PAGE_MAX\" environment profile_image: { description: "Profile image (640x640)", type: :string, format: :url }, profile_image_90: { description: "Profile image (90x90)", type: :string, format: :url } } + }, + SharedPodcast: { + description: "The podcast that the resource belongs to", + type: "object", + properties: { + title: { type: :string }, + slug: { type: :string }, + image_url: { description: "Podcast image url", type: :string, format: :url } + } } } } diff --git a/swagger/v1/api_v1.json b/swagger/v1/api_v1.json index fa7cf2e50..05f97d1d5 100644 --- a/swagger/v1/api_v1.json +++ b/swagger/v1/api_v1.json @@ -1163,6 +1163,48 @@ } } } + }, + "/api/podcast_episodes": { + "get": { + "summary": "PodcastEpisodeIndex", + "tags": ["podcast_episode_index"], + "description": "This endpoint allows the client to retrieve a list of podcast episodes.\n If username parameter is passed, episodes of the corresponding podcast will be returned\n The endpoint supports pagination, each page will contain `30` podcast episodes by default", + "operationId": "getPodcastEpisodes", + "parameters": [ + { + "name": "username", + "in": "query", + "required": false, + "description": "Using this parameter will retrieve episodes that belong to the podcast that has the specified slug (username).", + "schema": { + "type": "string" + }, + "example": "codenewbie" + }, + { + "$ref": "#/components/parameters/pageParam" + }, + { + "$ref": "#/components/parameters/perPageParam30to1000" + } + ], + "responses": { + "200": { + "description": "A list of articles in the users readinglist", + "content": { + "application/json": { + "example": [], + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ArticleIndex" + } + } + } + } + } + } + } } }, "servers": [ @@ -1423,6 +1465,45 @@ "reading_time_minutes" ] }, + "PodcastEpisodeIndex": { + "description": "Resprentation of a podcast episode returned in a list", + "type": "object", + "properties": { + "type_of": { + "type": "string" + }, + "id": { + "type": "integer", + "format": "int32" + }, + "class_name": { + "type": "string" + }, + "path": { + "type": "string", + "format": "path" + }, + "title": { + "type": "string" + }, + "image_url": { + "type": "string", + "format": "url" + }, + "podcast": { + "$ref": "#/components/schemas/SharedPodcast" + } + }, + "required": [ + "type_of", + "class_name", + "id", + "path", + "title", + "image_url", + "podcast" + ] + }, "SharedUser": { "description": "The resource creator", "type": "object", @@ -1480,6 +1561,23 @@ "format": "url" } } + }, + "SharedPodcast": { + "description": "The podcast the resource belongs to", + "type": "object", + "properties": { + "title": { + "type": "string" + }, + "slug": { + "type": "string" + }, + "image_url": { + "description": "Image", + "type": "string", + "format": "url" + } + } } } }