DEV: Add fetching likes info to api docs (#21028)

This commit adds some more detailed information about how to actually
get the number of likes for a post.

Also refactors some requests and responses into json schema files to
clean up the specs a bit.

See https://meta.discourse.org/t/69017/4?u=blake
This commit is contained in:
Blake Erickson 2023-04-10 09:07:10 -06:00 committed by GitHub
parent 569b923fb6
commit d289b20858
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 584 additions and 338 deletions

View File

@ -229,171 +229,31 @@ RSpec.describe "posts" do
get "Retrieve a single post" do
tags "Posts"
operationId "getPost"
parameter name: "Api-Key", in: :header, type: :string, required: true
parameter name: "Api-Username", in: :header, type: :string, required: true
consumes "application/json"
description <<~TEXT
This endpoint can be used to get the number of likes on a post using the
`actions_summary` property in the response. `actions_summary` responses
with the id of `2` signify a `like`. If there are no `actions_summary`
items with the id of `2`, that means there are 0 likes. Other ids likely
refer to various different flag types.
TEXT
expected_request_schema = nil
parameter name: :id, in: :path, schema: { type: :string }
produces "application/json"
response "200", "latest posts" do
schema type: :object,
properties: {
id: {
type: :integer,
},
name: {
type: %i[string null],
},
username: {
type: :string,
},
avatar_template: {
type: :string,
},
created_at: {
type: :string,
},
cooked: {
type: :string,
},
post_number: {
type: :integer,
},
post_type: {
type: :integer,
},
updated_at: {
type: :string,
},
reply_count: {
type: :integer,
},
reply_to_post_number: {
type: %i[string null],
},
quote_count: {
type: :integer,
},
incoming_link_count: {
type: :integer,
},
reads: {
type: :integer,
},
readers_count: {
type: :integer,
},
score: {
type: :integer,
},
yours: {
type: :boolean,
},
topic_id: {
type: :integer,
},
topic_slug: {
type: :string,
},
display_username: {
type: %i[string null],
},
primary_group_name: {
type: %i[string null],
},
flair_name: {
type: %i[string null],
},
flair_url: {
type: %i[string null],
},
flair_bg_color: {
type: %i[string null],
},
flair_color: {
type: %i[string null],
},
version: {
type: :integer,
},
can_edit: {
type: :boolean,
},
can_delete: {
type: :boolean,
},
can_recover: {
type: :boolean,
},
can_wiki: {
type: :boolean,
},
user_title: {
type: %i[string null],
},
raw: {
type: :string,
},
actions_summary: {
type: :array,
items: {
type: :object,
properties: {
id: {
type: :integer,
},
can_act: {
type: :boolean,
},
},
},
},
moderator: {
type: :boolean,
},
admin: {
type: :boolean,
},
staff: {
type: :boolean,
},
user_id: {
type: :integer,
},
hidden: {
type: :boolean,
},
trust_level: {
type: :integer,
},
deleted_at: {
type: %i[string null],
},
user_deleted: {
type: :boolean,
},
edit_reason: {
type: %i[string null],
},
can_view_edit_history: {
type: :boolean,
},
wiki: {
type: :boolean,
},
reviewable_id: {
type: %i[string null],
},
reviewable_score_count: {
type: :integer,
},
reviewable_score_pending_count: {
type: :integer,
},
}
response "200", "single post" do
expected_response_schema = load_spec_schema("post_show_response")
schema expected_response_schema
let(:id) { Fabricate(:post).id }
run_test!
it_behaves_like "a JSON endpoint", 200 do
let(:expected_response_schema) { expected_response_schema }
let(:expected_request_schema) { expected_request_schema }
end
end
end
@ -401,191 +261,18 @@ RSpec.describe "posts" do
tags "Posts"
operationId "updatePost"
consumes "application/json"
parameter name: "Api-Key", in: :header, type: :string, required: true
parameter name: "Api-Username", in: :header, type: :string, required: true
expected_request_schema = load_spec_schema("post_update_request")
parameter name: :id, in: :path, schema: { type: :string }
parameter name: :post_body,
in: :body,
schema: {
type: :object,
properties: {
post: {
type: :object,
properties: {
raw: {
type: :string,
},
edit_reason: {
type: :string,
},
},
required: ["raw"],
},
},
}
parameter name: :params, in: :body, schema: expected_request_schema
produces "application/json"
response "200", "post updated" do
schema type: :object,
properties: {
post: {
type: :object,
properties: {
id: {
type: :integer,
},
name: {
type: %i[string null],
},
username: {
type: :string,
},
avatar_template: {
type: :string,
},
created_at: {
type: :string,
},
cooked: {
type: :string,
},
post_number: {
type: :integer,
},
post_type: {
type: :integer,
},
updated_at: {
type: :string,
},
reply_count: {
type: :integer,
},
reply_to_post_number: {
type: %i[string null],
},
quote_count: {
type: :integer,
},
incoming_link_count: {
type: :integer,
},
reads: {
type: :integer,
},
readers_count: {
type: :integer,
},
score: {
type: :number,
},
yours: {
type: :boolean,
},
topic_id: {
type: :integer,
},
topic_slug: {
type: :string,
},
display_username: {
type: %i[string null],
},
primary_group_name: {
type: %i[string null],
},
flair_url: {
type: %i[string null],
},
flair_bg_color: {
type: %i[string null],
},
flair_color: {
type: %i[string null],
},
version: {
type: :integer,
},
can_edit: {
type: :boolean,
},
can_delete: {
type: :boolean,
},
can_recover: {
type: :boolean,
},
can_wiki: {
type: :boolean,
},
user_title: {
type: %i[string null],
},
actions_summary: {
type: :array,
items: {
type: :object,
properties: {
id: {
type: :integer,
},
can_act: {
type: :boolean,
},
},
},
},
moderator: {
type: :boolean,
},
admin: {
type: :boolean,
},
staff: {
type: :boolean,
},
user_id: {
type: :integer,
},
draft_sequence: {
type: :integer,
},
hidden: {
type: :boolean,
},
trust_level: {
type: :integer,
},
deleted_at: {
type: %i[string null],
},
user_deleted: {
type: :boolean,
},
edit_reason: {
type: %i[string null],
},
can_view_edit_history: {
type: :boolean,
},
wiki: {
type: :boolean,
},
reviewable_id: {
type: %i[string null],
},
reviewable_score_count: {
type: :integer,
},
reviewable_score_pending_count: {
type: :integer,
},
},
},
}
expected_response_schema = load_spec_schema("post_update_response")
schema expected_response_schema
let(:post_body) { { post: { raw: "Updated content!", edit_reason: "fixed typo" } } }
let(:params) do
{ "post" => { "raw" => "Updated content!", "edit_reason" => "fixed typo" } }
end
let(:id) { Fabricate(:post).id }
run_test! do |response|
@ -593,6 +280,11 @@ RSpec.describe "posts" do
expect(data["post"]["cooked"]).to eq("<p>Updated content!</p>")
expect(data["post"]["edit_reason"]).to eq("fixed typo")
end
it_behaves_like "a JSON endpoint", 200 do
let(:expected_response_schema) { expected_response_schema }
let(:expected_request_schema) { expected_request_schema }
end
end
end

View File

@ -0,0 +1,266 @@
{
"additionalProperties": true,
"properties": {
"id": {
"type": "integer"
},
"username": {
"type": "string"
},
"avatar_template": {
"type": "string"
},
"created_at": {
"type": "string"
},
"cooked": {
"type": "string"
},
"post_number": {
"type": "integer"
},
"post_type": {
"type": "integer"
},
"updated_at": {
"type": "string"
},
"reply_count": {
"type": "integer"
},
"reply_to_post_number": {
"type": [
"string",
"null"
]
},
"quote_count": {
"type": "integer"
},
"incoming_link_count": {
"type": "integer"
},
"reads": {
"type": "integer"
},
"readers_count": {
"type": "integer"
},
"score": {
"type": ""
},
"yours": {
"type": "boolean"
},
"topic_id": {
"type": "integer"
},
"topic_slug": {
"type": "string"
},
"primary_group_name": {
"type": [
"string",
"null"
]
},
"flair_name": {
"type": [
"string",
"null"
]
},
"flair_url": {
"type": [
"string",
"null"
]
},
"flair_bg_color": {
"type": [
"string",
"null"
]
},
"flair_color": {
"type": [
"string",
"null"
]
},
"version": {
"type": "integer"
},
"can_edit": {
"type": "boolean"
},
"can_delete": {
"type": "boolean"
},
"can_recover": {
"type": "boolean"
},
"can_wiki": {
"type": "boolean"
},
"user_title": {
"type": [
"string",
"null"
]
},
"bookmarked": {
"type": "boolean"
},
"raw": {
"type": "string"
},
"actions_summary": {
"type": "array",
"items": [
{
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "integer",
"description": "`2`: like, `3`, `4`, `6`, `7`, `8`: flag"
},
"count": {
"type": "integer"
},
"acted": {
"type": "boolean"
},
"can_undo": {
"type": "boolean"
},
"can_act": {
"type": "boolean"
}
},
"required": [
"id"
]
}
]
},
"moderator": {
"type": "boolean"
},
"admin": {
"type": "boolean"
},
"staff": {
"type": "boolean"
},
"user_id": {
"type": "integer"
},
"hidden": {
"type": "boolean"
},
"trust_level": {
"type": "integer"
},
"deleted_at": {
"type": [
"string",
"null"
]
},
"user_deleted": {
"type": "boolean"
},
"edit_reason": {
"type": [
"string",
"null"
]
},
"can_view_edit_history": {
"type": "boolean"
},
"wiki": {
"type": "boolean"
},
"reviewable_id": {
"type": [
"string",
"null"
]
},
"reviewable_score_count": {
"type": "integer"
},
"reviewable_score_pending_count": {
"type": "integer"
},
"mentioned_users": {
"type": "array",
"items": [
]
},
"name": {
"type": [
"string",
"null"
]
},
"display_username": {
"type": [
"string",
"null"
]
}
},
"required": [
"id",
"username",
"avatar_template",
"created_at",
"cooked",
"post_number",
"post_type",
"updated_at",
"reply_count",
"reply_to_post_number",
"quote_count",
"incoming_link_count",
"reads",
"readers_count",
"score",
"yours",
"topic_id",
"topic_slug",
"primary_group_name",
"flair_name",
"flair_url",
"flair_bg_color",
"flair_color",
"version",
"can_edit",
"can_delete",
"can_recover",
"can_wiki",
"user_title",
"bookmarked",
"raw",
"actions_summary",
"moderator",
"admin",
"staff",
"user_id",
"hidden",
"trust_level",
"deleted_at",
"user_deleted",
"edit_reason",
"can_view_edit_history",
"wiki",
"reviewable_id",
"reviewable_score_count",
"reviewable_score_pending_count"
]
}

View File

@ -0,0 +1,18 @@
{
"additionalProperties": false,
"properties": {
"post": {
"type": "object",
"additionalProperties": false,
"properties": {
"raw": {
"type": "string"
},
"edit_reason": {
"type": "string"
}
},
"required": ["raw"]
}
}
}

View File

@ -0,0 +1,270 @@
{
"additionalProperties": false,
"properties": {
"post": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "integer"
},
"username": {
"type": "string"
},
"avatar_template": {
"type": "string"
},
"created_at": {
"type": "string"
},
"cooked": {
"type": "string"
},
"post_number": {
"type": "integer"
},
"post_type": {
"type": "integer"
},
"updated_at": {
"type": "string"
},
"reply_count": {
"type": "integer"
},
"reply_to_post_number": {
"type": [
"string",
"null"
]
},
"quote_count": {
"type": "integer"
},
"incoming_link_count": {
"type": "integer"
},
"reads": {
"type": "integer"
},
"readers_count": {
"type": "integer"
},
"score": {
"type": ""
},
"yours": {
"type": "boolean"
},
"topic_id": {
"type": "integer"
},
"topic_slug": {
"type": "string"
},
"primary_group_name": {
"type": [
"string",
"null"
]
},
"flair_name": {
"type": [
"string",
"null"
]
},
"flair_url": {
"type": [
"string",
"null"
]
},
"flair_bg_color": {
"type": [
"string",
"null"
]
},
"flair_color": {
"type": [
"string",
"null"
]
},
"version": {
"type": "integer"
},
"can_edit": {
"type": "boolean"
},
"can_delete": {
"type": "boolean"
},
"can_recover": {
"type": "boolean"
},
"can_wiki": {
"type": "boolean"
},
"user_title": {
"type": [
"string",
"null"
]
},
"bookmarked": {
"type": "boolean"
},
"raw": {
"type": "string"
},
"actions_summary": {
"type": "array",
"items": [
{
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "integer"
},
"can_act": {
"type": "boolean"
}
},
"required": [
"id",
"can_act"
]
}
]
},
"moderator": {
"type": "boolean"
},
"admin": {
"type": "boolean"
},
"staff": {
"type": "boolean"
},
"user_id": {
"type": "integer"
},
"draft_sequence": {
"type": "integer"
},
"hidden": {
"type": "boolean"
},
"trust_level": {
"type": "integer"
},
"deleted_at": {
"type": [
"string",
"null"
]
},
"user_deleted": {
"type": "boolean"
},
"edit_reason": {
"type": [
"string",
"null"
]
},
"can_view_edit_history": {
"type": "boolean"
},
"wiki": {
"type": "boolean"
},
"reviewable_id": {
"type": [
"string",
"null"
]
},
"reviewable_score_count": {
"type": "integer"
},
"reviewable_score_pending_count": {
"type": "integer"
},
"mentioned_users": {
"type": "array",
"items": [
]
},
"name": {
"type": [
"string",
"null"
]
},
"display_username": {
"type": [
"string",
"null"
]
}
},
"required": [
"id",
"username",
"avatar_template",
"created_at",
"cooked",
"post_number",
"post_type",
"updated_at",
"reply_count",
"reply_to_post_number",
"quote_count",
"incoming_link_count",
"reads",
"readers_count",
"score",
"yours",
"topic_id",
"topic_slug",
"primary_group_name",
"flair_name",
"flair_url",
"flair_bg_color",
"flair_color",
"version",
"can_edit",
"can_delete",
"can_recover",
"can_wiki",
"user_title",
"bookmarked",
"raw",
"actions_summary",
"moderator",
"admin",
"staff",
"user_id",
"draft_sequence",
"hidden",
"trust_level",
"deleted_at",
"user_deleted",
"edit_reason",
"can_view_edit_history",
"wiki",
"reviewable_id",
"reviewable_score_count",
"reviewable_score_pending_count"
]
}
},
"required": [
"post"
]
}