From 5c6e7e3401f23b7e1673e8039dceb2e5b9c3f008 Mon Sep 17 00:00:00 2001 From: Blake Erickson Date: Tue, 3 Aug 2021 06:25:12 -0600 Subject: [PATCH] DEV: Document some of the badge api endpoints (#13919) Adding some api documentation for the badge routes. --- spec/requests/api/badges_spec.rb | 105 ++++++++ .../schemas/json/badge_create_request.json | 17 ++ .../schemas/json/badge_create_response.json | 135 ++++++++++ .../api/schemas/json/badge_list_response.json | 251 ++++++++++++++++++ .../schemas/json/badge_update_request.json | 17 ++ .../schemas/json/badge_update_response.json | 135 ++++++++++ .../schemas/json/user_badges_response.json | 201 ++++++++++++++ spec/requests/api/user_badges_spec.rb | 35 +++ 8 files changed, 896 insertions(+) create mode 100644 spec/requests/api/badges_spec.rb create mode 100644 spec/requests/api/schemas/json/badge_create_request.json create mode 100644 spec/requests/api/schemas/json/badge_create_response.json create mode 100644 spec/requests/api/schemas/json/badge_list_response.json create mode 100644 spec/requests/api/schemas/json/badge_update_request.json create mode 100644 spec/requests/api/schemas/json/badge_update_response.json create mode 100644 spec/requests/api/schemas/json/user_badges_response.json create mode 100644 spec/requests/api/user_badges_spec.rb diff --git a/spec/requests/api/badges_spec.rb b/spec/requests/api/badges_spec.rb new file mode 100644 index 00000000000..92a8ad518b8 --- /dev/null +++ b/spec/requests/api/badges_spec.rb @@ -0,0 +1,105 @@ +# frozen_string_literal: true +require 'swagger_helper' + +describe 'badges' do + + let(:admin) { Fabricate(:admin) } + let(:badge) { Fabricate(:badge) } + + before do + Jobs.run_immediately! + sign_in(admin) + end + + path '/admin/badges.json' do + + get 'List badges' do + tags 'Badges' + consumes 'application/json' + expected_request_schema = nil + + produces 'application/json' + response '200', 'success response' do + expected_response_schema = load_spec_schema('badge_list_response') + schema expected_response_schema + + 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 + + post 'Create badge' do + tags 'Badges' + consumes 'application/json' + expected_request_schema = load_spec_schema('badge_create_request') + parameter name: :params, in: :body, schema: expected_request_schema + + produces 'application/json' + response '200', 'success response' do + expected_response_schema = load_spec_schema('badge_create_response') + schema expected_response_schema + + let(:params) { { + 'name' => 'badge1', + 'badge_type_id' => 2 + } } + + 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 + end + + path '/admin/badges/{id}.json' do + + put 'Update badge' do + tags 'Badges' + consumes 'application/json' + expected_request_schema = load_spec_schema('badge_update_request') + parameter name: :id, in: :path, schema: { type: :integer } + parameter name: :params, in: :body, schema: expected_request_schema + + produces 'application/json' + response '200', 'success response' do + expected_response_schema = load_spec_schema('badge_update_response') + schema expected_response_schema + + let(:id) { badge.id } + + let(:params) { { + 'name' => 'badge1', + 'badge_type_id' => 2 + } } + + 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 + + delete 'Delete badge' do + tags 'Badges' + consumes 'application/json' + expected_request_schema = nil + parameter name: :id, in: :path, schema: { type: :integer } + + produces 'application/json' + response '200', 'success response' do + expected_response_schema = nil + schema expected_response_schema + + let(:id) { badge.id } + + 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 + end +end diff --git a/spec/requests/api/schemas/json/badge_create_request.json b/spec/requests/api/schemas/json/badge_create_request.json new file mode 100644 index 00000000000..1f2314dec0e --- /dev/null +++ b/spec/requests/api/schemas/json/badge_create_request.json @@ -0,0 +1,17 @@ +{ + "additionalProperties": false, + "properties": { + "name": { + "type": "string", + "description": "The name for the new badge." + }, + "badge_type_id": { + "type": "integer", + "description": "The ID for the badge type. 1 for Gold, 2 for Silver, 3 for Bronze." + } + }, + "required": [ + "name", + "badge_type_id" + ] +} diff --git a/spec/requests/api/schemas/json/badge_create_response.json b/spec/requests/api/schemas/json/badge_create_response.json new file mode 100644 index 00000000000..74d57a1ec7e --- /dev/null +++ b/spec/requests/api/schemas/json/badge_create_response.json @@ -0,0 +1,135 @@ +{ + "additionalProperties": false, + "properties": { + "badge_types": { + "type": "array", + "items": [ + { + "type": "object", + "additionalProperties": false, + "properties": { + "id": { + "type": "integer" + }, + "name": { + "type": "string" + }, + "sort_order": { + "type": "integer" + } + }, + "required": [ + "id", + "name", + "sort_order" + ] + } + ] + }, + "badge": { + "type": "object", + "additionalProperties": false, + "properties": { + "id": { + "type": "integer" + }, + "name": { + "type": "string" + }, + "description": { + "type": "string" + }, + "grant_count": { + "type": "integer" + }, + "allow_title": { + "type": "boolean" + }, + "multiple_grant": { + "type": "boolean" + }, + "icon": { + "type": "string" + }, + "image_url": { + "type": [ + "string", + "null" + ] + }, + "listable": { + "type": "boolean" + }, + "enabled": { + "type": "boolean" + }, + "badge_grouping_id": { + "type": "integer" + }, + "system": { + "type": "boolean" + }, + "long_description": { + "type": "string" + }, + "slug": { + "type": "string" + }, + "manually_grantable": { + "type": "boolean" + }, + "query": { + "type": [ + "string", + "null" + ] + }, + "trigger": { + "type": [ + "string", + "null" + ] + }, + "target_posts": { + "type": "boolean" + }, + "auto_revoke": { + "type": "boolean" + }, + "show_posts": { + "type": "boolean" + }, + "badge_type_id": { + "type": "integer" + } + }, + "required": [ + "id", + "name", + "description", + "grant_count", + "allow_title", + "multiple_grant", + "icon", + "image_url", + "listable", + "enabled", + "badge_grouping_id", + "system", + "long_description", + "slug", + "manually_grantable", + "query", + "trigger", + "target_posts", + "auto_revoke", + "show_posts", + "badge_type_id" + ] + } + }, + "required": [ + "badge_types", + "badge" + ] +} diff --git a/spec/requests/api/schemas/json/badge_list_response.json b/spec/requests/api/schemas/json/badge_list_response.json new file mode 100644 index 00000000000..6179c106cfd --- /dev/null +++ b/spec/requests/api/schemas/json/badge_list_response.json @@ -0,0 +1,251 @@ +{ + "additionalProperties": false, + "properties": { + "badges": { + "type": "array", + "items": [ + { + "type": "object", + "additionalProperties": false, + "properties": { + "id": { + "type": "integer" + }, + "name": { + "type": "string" + }, + "description": { + "type": "string" + }, + "grant_count": { + "type": "integer" + }, + "allow_title": { + "type": "boolean" + }, + "multiple_grant": { + "type": "boolean" + }, + "icon": { + "type": "string" + }, + "image_url": { + "type": [ + "string", + "null" + ] + }, + "listable": { + "type": "boolean" + }, + "enabled": { + "type": "boolean" + }, + "badge_grouping_id": { + "type": "integer" + }, + "system": { + "type": "boolean" + }, + "long_description": { + "type": "string" + }, + "slug": { + "type": "string" + }, + "manually_grantable": { + "type": "boolean" + }, + "query": { + "type": [ + "string", + "null" + ] + }, + "trigger": { + "type": [ + "integer", + "null" + ] + }, + "target_posts": { + "type": "boolean" + }, + "auto_revoke": { + "type": "boolean" + }, + "show_posts": { + "type": "boolean" + }, + "i18n_name": { + "type": "string" + }, + "badge_type_id": { + "type": "integer" + } + }, + "required": [ + "id", + "name", + "description", + "grant_count", + "allow_title", + "multiple_grant", + "icon", + "image_url", + "listable", + "enabled", + "badge_grouping_id", + "system", + "long_description", + "slug", + "manually_grantable", + "query", + "trigger", + "target_posts", + "auto_revoke", + "show_posts", + "i18n_name", + "badge_type_id" + ] + } + ] + }, + "badge_types": { + "type": "array", + "items": [ + { + "type": "object", + "additionalProperties": false, + "properties": { + "id": { + "type": "integer" + }, + "name": { + "type": "string" + }, + "sort_order": { + "type": "integer" + } + }, + "required": [ + "id", + "name", + "sort_order" + ] + } + ] + }, + "badge_groupings": { + "type": "array", + "items": [ + { + "type": "object", + "additionalProperties": false, + "properties": { + "id": { + "type": "integer" + }, + "name": { + "type": "string" + }, + "description": { + "type": [ + "string", + "null" + ] + }, + "position": { + "type": "integer" + }, + "system": { + "type": "boolean" + } + }, + "required": [ + "id", + "name", + "description", + "position", + "system" + ] + } + ] + }, + "admin_badges": { + "type": "object", + "additionalProperties": false, + "properties": { + "protected_system_fields": { + "type": "array", + "items": [ + + ] + }, + "triggers": { + "type": "object", + "additionalProperties": false, + "properties": { + "user_change": { + "type": "integer" + }, + "none": { + "type": "integer" + }, + "post_revision": { + "type": "integer" + }, + "trust_level_change": { + "type": "integer" + }, + "post_processed": { + "type": "integer" + }, + "post_action": { + "type": "integer" + } + }, + "required": [ + "user_change", + "none", + "post_revision", + "trust_level_change", + "post_processed", + "post_action" + ] + }, + "badge_ids": { + "type": "array", + "items": [ + + ] + }, + "badge_grouping_ids": { + "type": "array", + "items": [ + + ] + }, + "badge_type_ids": { + "type": "array", + "items": [ + + ] + } + }, + "required": [ + "protected_system_fields", + "triggers", + "badge_ids", + "badge_grouping_ids", + "badge_type_ids" + ] + } + }, + "required": [ + "badges", + "badge_types", + "badge_groupings", + "admin_badges" + ] +} diff --git a/spec/requests/api/schemas/json/badge_update_request.json b/spec/requests/api/schemas/json/badge_update_request.json new file mode 100644 index 00000000000..1f2314dec0e --- /dev/null +++ b/spec/requests/api/schemas/json/badge_update_request.json @@ -0,0 +1,17 @@ +{ + "additionalProperties": false, + "properties": { + "name": { + "type": "string", + "description": "The name for the new badge." + }, + "badge_type_id": { + "type": "integer", + "description": "The ID for the badge type. 1 for Gold, 2 for Silver, 3 for Bronze." + } + }, + "required": [ + "name", + "badge_type_id" + ] +} diff --git a/spec/requests/api/schemas/json/badge_update_response.json b/spec/requests/api/schemas/json/badge_update_response.json new file mode 100644 index 00000000000..74d57a1ec7e --- /dev/null +++ b/spec/requests/api/schemas/json/badge_update_response.json @@ -0,0 +1,135 @@ +{ + "additionalProperties": false, + "properties": { + "badge_types": { + "type": "array", + "items": [ + { + "type": "object", + "additionalProperties": false, + "properties": { + "id": { + "type": "integer" + }, + "name": { + "type": "string" + }, + "sort_order": { + "type": "integer" + } + }, + "required": [ + "id", + "name", + "sort_order" + ] + } + ] + }, + "badge": { + "type": "object", + "additionalProperties": false, + "properties": { + "id": { + "type": "integer" + }, + "name": { + "type": "string" + }, + "description": { + "type": "string" + }, + "grant_count": { + "type": "integer" + }, + "allow_title": { + "type": "boolean" + }, + "multiple_grant": { + "type": "boolean" + }, + "icon": { + "type": "string" + }, + "image_url": { + "type": [ + "string", + "null" + ] + }, + "listable": { + "type": "boolean" + }, + "enabled": { + "type": "boolean" + }, + "badge_grouping_id": { + "type": "integer" + }, + "system": { + "type": "boolean" + }, + "long_description": { + "type": "string" + }, + "slug": { + "type": "string" + }, + "manually_grantable": { + "type": "boolean" + }, + "query": { + "type": [ + "string", + "null" + ] + }, + "trigger": { + "type": [ + "string", + "null" + ] + }, + "target_posts": { + "type": "boolean" + }, + "auto_revoke": { + "type": "boolean" + }, + "show_posts": { + "type": "boolean" + }, + "badge_type_id": { + "type": "integer" + } + }, + "required": [ + "id", + "name", + "description", + "grant_count", + "allow_title", + "multiple_grant", + "icon", + "image_url", + "listable", + "enabled", + "badge_grouping_id", + "system", + "long_description", + "slug", + "manually_grantable", + "query", + "trigger", + "target_posts", + "auto_revoke", + "show_posts", + "badge_type_id" + ] + } + }, + "required": [ + "badge_types", + "badge" + ] +} diff --git a/spec/requests/api/schemas/json/user_badges_response.json b/spec/requests/api/schemas/json/user_badges_response.json new file mode 100644 index 00000000000..9030ae2a1fd --- /dev/null +++ b/spec/requests/api/schemas/json/user_badges_response.json @@ -0,0 +1,201 @@ +{ + "additionalProperties": false, + "properties": { + "badges": { + "type": "array", + "items": [ + { + "type": "object", + "additionalProperties": false, + "properties": { + "id": { + "type": "integer" + }, + "name": { + "type": "string" + }, + "description": { + "type": "string" + }, + "grant_count": { + "type": "integer" + }, + "allow_title": { + "type": "boolean" + }, + "multiple_grant": { + "type": "boolean" + }, + "icon": { + "type": "string" + }, + "image_url": { + "type": [ + "string", + "null" + ] + }, + "listable": { + "type": "boolean" + }, + "enabled": { + "type": "boolean" + }, + "badge_grouping_id": { + "type": "integer" + }, + "system": { + "type": "boolean" + }, + "slug": { + "type": "string" + }, + "manually_grantable": { + "type": "boolean" + }, + "badge_type_id": { + "type": "integer" + } + }, + "required": [ + "id", + "name", + "description", + "grant_count", + "allow_title", + "multiple_grant", + "icon", + "image_url", + "listable", + "enabled", + "badge_grouping_id", + "system", + "slug", + "manually_grantable", + "badge_type_id" + ] + } + ] + }, + "badge_types": { + "type": "array", + "items": [ + { + "type": "object", + "additionalProperties": false, + "properties": { + "id": { + "type": "integer" + }, + "name": { + "type": "string" + }, + "sort_order": { + "type": "integer" + } + }, + "required": [ + "id", + "name", + "sort_order" + ] + } + ] + }, + "granted_bies": { + "type": "array", + "items": [ + { + "type": "object", + "additionalProperties": false, + "properties": { + "id": { + "type": "integer" + }, + "username": { + "type": "string" + }, + "name": { + "type": "string" + }, + "avatar_template": { + "type": "string" + }, + "flair_name": { + "type": [ + "string", + "null" + ] + }, + "admin": { + "type": "boolean" + }, + "moderator": { + "type": "boolean" + }, + "trust_level": { + "type": "integer" + } + }, + "required": [ + "id", + "username", + "name", + "avatar_template", + "flair_name", + "admin", + "moderator", + "trust_level" + ] + } + ] + }, + "user_badges": { + "type": "array", + "items": [ + { + "type": "object", + "additionalProperties": false, + "properties": { + "id": { + "type": "integer" + }, + "granted_at": { + "type": "string" + }, + "grouping_position": { + "type": "integer" + }, + "is_favorite": { + "type": [ + "string", + "null" + ] + }, + "can_favorite": { + "type": "boolean" + }, + "badge_id": { + "type": "integer" + }, + "granted_by_id": { + "type": "integer" + } + }, + "required": [ + "id", + "granted_at", + "grouping_position", + "is_favorite", + "can_favorite", + "badge_id", + "granted_by_id" + ] + } + ] + } + }, + "required": [ + "user_badges" + ] +} diff --git a/spec/requests/api/user_badges_spec.rb b/spec/requests/api/user_badges_spec.rb new file mode 100644 index 00000000000..5f2e448e2ce --- /dev/null +++ b/spec/requests/api/user_badges_spec.rb @@ -0,0 +1,35 @@ +# frozen_string_literal: true +require 'swagger_helper' + +describe 'user_badges' do + + let(:admin) { Fabricate(:admin) } + + before do + Jobs.run_immediately! + sign_in(admin) + end + + path '/user-badges/{username}.json' do + + get 'List badges for a user' do + tags 'Badges, Users' + consumes 'application/json' + expected_request_schema = nil + parameter name: :username, in: :path, schema: { type: :string } + + produces 'application/json' + response '200', 'success response' do + expected_response_schema = load_spec_schema('user_badges_response') + schema expected_response_schema + + let(:username) { admin.username } + + 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 + end +end