[API V1 docs] Podcast Episodes (#18908)
* Podcast episodes api swagger docs (start) * Podcast Episodes api swagger docs * Fixed wording Co-authored-by: Ridhwana <Ridhwana.Khan16@gmail.com> * Fixed wording Co-authored-by: Ridhwana <Ridhwana.Khan16@gmail.com> * Removed commented code Co-authored-by: Ridhwana <Ridhwana.Khan16@gmail.com>
This commit is contained in:
Anna Buianova
GitHub
parent
6e8034eee2
commit
a2d26df17b
3 changed files with 185 additions and 1 deletions
63
spec/requests/api/v1/docs/podcast_episodes_spec.rb
Normal file
63
spec/requests/api/v1/docs/podcast_episodes_spec.rb
Normal file
|
|
@ -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
|
||||
|
|
@ -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 }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
|
|||
|
|
@ -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"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue