From 29db669cc9c076fd3d4e35693e8921193a7d5844 Mon Sep 17 00:00:00 2001 From: Sarah Edwards Date: Tue, 27 Jun 2023 09:22:19 -0700 Subject: [PATCH] Make all REST categories have subcategories (#38559) Co-authored-by: Rachael Sewell --- .eslintrc.cjs | 2 +- content/rest/{ => billing}/billing.md | 0 content/rest/billing/index.md | 15 +++++ .../rest/{ => code-scanning}/code-scanning.md | 0 content/rest/code-scanning/index.md | 20 +++++++ .../codes-of-conduct.md | 0 content/rest/codes-of-conduct/index.md | 18 ++++++ content/rest/{ => deploy-keys}/deploy-keys.md | 0 content/rest/deploy-keys/index.md | 17 ++++++ content/rest/{ => emojis}/emojis.md | 0 content/rest/emojis/index.md | 20 +++++++ content/rest/{ => gitignore}/gitignore.md | 0 content/rest/gitignore/index.md | 18 ++++++ content/rest/licenses/index.md | 18 ++++++ content/rest/{ => licenses}/licenses.md | 0 content/rest/markdown/index.md | 18 ++++++ content/rest/{ => markdown}/markdown.md | 0 content/rest/meta/index.md | 21 +++++++ content/rest/{ => meta}/meta.md | 0 content/rest/oauth-authorizations/index.md | 13 +++++ .../oauth-authorizations.md | 0 content/rest/packages/index.md | 17 ++++++ content/rest/{ => packages}/packages.md | 0 content/rest/pages/index.md | 20 +++++++ content/rest/{ => pages}/pages.md | 0 content/rest/rate-limit/index.md | 16 ++++++ content/rest/{ => rate-limit}/rate-limit.md | 0 content/rest/reactions/index.md | 18 ++++++ content/rest/{ => reactions}/reactions.md | 0 content/rest/scim/index.md | 15 +++++ content/rest/{ => scim}/scim.md | 0 content/rest/search/index.md | 18 ++++++ content/rest/{ => search}/search.md | 0 content/rest/secret-scanning/index.md | 16 ++++++ .../{ => secret-scanning}/secret-scanning.md | 0 src/rest/scripts/utils/update-markdown.js | 27 +-------- src/rest/tests/rendering.js | 55 ++++++++++++++++++- tests/routing/redirects.js | 48 ---------------- 38 files changed, 355 insertions(+), 75 deletions(-) rename content/rest/{ => billing}/billing.md (100%) create mode 100644 content/rest/billing/index.md rename content/rest/{ => code-scanning}/code-scanning.md (100%) create mode 100644 content/rest/code-scanning/index.md rename content/rest/{ => codes-of-conduct}/codes-of-conduct.md (100%) create mode 100644 content/rest/codes-of-conduct/index.md rename content/rest/{ => deploy-keys}/deploy-keys.md (100%) create mode 100644 content/rest/deploy-keys/index.md rename content/rest/{ => emojis}/emojis.md (100%) create mode 100644 content/rest/emojis/index.md rename content/rest/{ => gitignore}/gitignore.md (100%) create mode 100644 content/rest/gitignore/index.md create mode 100644 content/rest/licenses/index.md rename content/rest/{ => licenses}/licenses.md (100%) create mode 100644 content/rest/markdown/index.md rename content/rest/{ => markdown}/markdown.md (100%) create mode 100644 content/rest/meta/index.md rename content/rest/{ => meta}/meta.md (100%) create mode 100644 content/rest/oauth-authorizations/index.md rename content/rest/{ => oauth-authorizations}/oauth-authorizations.md (100%) create mode 100644 content/rest/packages/index.md rename content/rest/{ => packages}/packages.md (100%) create mode 100644 content/rest/pages/index.md rename content/rest/{ => pages}/pages.md (100%) create mode 100644 content/rest/rate-limit/index.md rename content/rest/{ => rate-limit}/rate-limit.md (100%) create mode 100644 content/rest/reactions/index.md rename content/rest/{ => reactions}/reactions.md (100%) create mode 100644 content/rest/scim/index.md rename content/rest/{ => scim}/scim.md (100%) create mode 100644 content/rest/search/index.md rename content/rest/{ => search}/search.md (100%) create mode 100644 content/rest/secret-scanning/index.md rename content/rest/{ => secret-scanning}/secret-scanning.md (100%) diff --git a/.eslintrc.cjs b/.eslintrc.cjs index 8251ed7fd2..54d54ca998 100644 --- a/.eslintrc.cjs +++ b/.eslintrc.cjs @@ -13,7 +13,7 @@ module.exports = { babelOptions: { configFile: './.babelrc' }, sourceType: 'module', }, - ignorePatterns: ['tmp/*', '!/.*', '/.next/', 'script/bookmarklets/*'], + ignorePatterns: ['tmp/*', '!/.*', '/.next/', 'script/bookmarklets/*', 'rest-api-description/'], rules: { 'import/no-extraneous-dependencies': ['error', { packageDir: '.' }], }, diff --git a/content/rest/billing.md b/content/rest/billing/billing.md similarity index 100% rename from content/rest/billing.md rename to content/rest/billing/billing.md diff --git a/content/rest/billing/index.md b/content/rest/billing/index.md new file mode 100644 index 0000000000..567cb7d4d4 --- /dev/null +++ b/content/rest/billing/index.md @@ -0,0 +1,15 @@ +--- +title: Billing +intro: Use the REST API to get billing information for an enterprise. +topics: + - API +versions: + fpt: '*' + ghec: '*' + ghes: '*' +children: + - /billing +autogenerated: rest +--- + + diff --git a/content/rest/code-scanning.md b/content/rest/code-scanning/code-scanning.md similarity index 100% rename from content/rest/code-scanning.md rename to content/rest/code-scanning/code-scanning.md diff --git a/content/rest/code-scanning/index.md b/content/rest/code-scanning/index.md new file mode 100644 index 0000000000..fd21e03dee --- /dev/null +++ b/content/rest/code-scanning/index.md @@ -0,0 +1,20 @@ +--- +title: Code Scanning +intro: >- + Use the REST API to retrieve and update {% data + variables.product.prodname_code_scanning %} alerts from a repository. +versions: + fpt: '*' + ghae: '*' + ghec: '*' + ghes: '*' +topics: + - API + - Code scanning + - REST +children: + - /code-scanning +autogenerated: rest +--- + + diff --git a/content/rest/codes-of-conduct.md b/content/rest/codes-of-conduct/codes-of-conduct.md similarity index 100% rename from content/rest/codes-of-conduct.md rename to content/rest/codes-of-conduct/codes-of-conduct.md diff --git a/content/rest/codes-of-conduct/index.md b/content/rest/codes-of-conduct/index.md new file mode 100644 index 0000000000..f5f1a51e57 --- /dev/null +++ b/content/rest/codes-of-conduct/index.md @@ -0,0 +1,18 @@ +--- +title: Codes of conduct +intro: Use the REST API to get information about codes of conduct. +versions: + fpt: '*' + ghae: '*' + ghec: '*' + ghes: '*' +topics: + - API +children: + - /codes-of-conduct +autogenerated: rest +--- + + + + diff --git a/content/rest/deploy-keys.md b/content/rest/deploy-keys/deploy-keys.md similarity index 100% rename from content/rest/deploy-keys.md rename to content/rest/deploy-keys/deploy-keys.md diff --git a/content/rest/deploy-keys/index.md b/content/rest/deploy-keys/index.md new file mode 100644 index 0000000000..f263d49dbc --- /dev/null +++ b/content/rest/deploy-keys/index.md @@ -0,0 +1,17 @@ +--- +title: Deploy keys +intro: Use the REST API to create and manage deploy keys. +versions: + fpt: '*' + ghae: '*' + ghec: '*' + ghes: '*' +topics: + - API +allowTitleToDifferFromFilename: true +children: + - /deploy-keys +autogenerated: rest +--- + + diff --git a/content/rest/emojis.md b/content/rest/emojis/emojis.md similarity index 100% rename from content/rest/emojis.md rename to content/rest/emojis/emojis.md diff --git a/content/rest/emojis/index.md b/content/rest/emojis/index.md new file mode 100644 index 0000000000..4e4e863e8b --- /dev/null +++ b/content/rest/emojis/index.md @@ -0,0 +1,20 @@ +--- +title: Emojis +intro: >- + Use the REST API to list and view all the available emojis to use on {% data + variables.product.product_name %}. +versions: + fpt: '*' + ghae: '*' + ghec: '*' + ghes: '*' +topics: + - API +children: + - /emojis +autogenerated: rest +--- + + + + diff --git a/content/rest/gitignore.md b/content/rest/gitignore/gitignore.md similarity index 100% rename from content/rest/gitignore.md rename to content/rest/gitignore/gitignore.md diff --git a/content/rest/gitignore/index.md b/content/rest/gitignore/index.md new file mode 100644 index 0000000000..f0e81e6d92 --- /dev/null +++ b/content/rest/gitignore/index.md @@ -0,0 +1,18 @@ +--- +title: Gitignore +intro: >- + Use the REST API to get `.gitignore` templates that can be used to ignore + files and directories. +versions: + fpt: '*' + ghae: '*' + ghec: '*' + ghes: '*' +topics: + - API +children: + - /gitignore +autogenerated: rest +--- + + diff --git a/content/rest/licenses/index.md b/content/rest/licenses/index.md new file mode 100644 index 0000000000..fdc55c3990 --- /dev/null +++ b/content/rest/licenses/index.md @@ -0,0 +1,18 @@ +--- +title: Licenses +intro: >- + Use the REST API to retrieve popular open source licenses and information + about a particular project's license file. +versions: + fpt: '*' + ghae: '*' + ghec: '*' + ghes: '*' +topics: + - API +children: + - /licenses +autogenerated: rest +--- + + diff --git a/content/rest/licenses.md b/content/rest/licenses/licenses.md similarity index 100% rename from content/rest/licenses.md rename to content/rest/licenses/licenses.md diff --git a/content/rest/markdown/index.md b/content/rest/markdown/index.md new file mode 100644 index 0000000000..af008a8699 --- /dev/null +++ b/content/rest/markdown/index.md @@ -0,0 +1,18 @@ +--- +title: Markdown +intro: Use the REST API to render a markdown document as an HTML page or as raw text. +versions: + fpt: '*' + ghae: '*' + ghec: '*' + ghes: '*' +topics: + - API +children: + - /markdown +autogenerated: rest +--- + + + + diff --git a/content/rest/markdown.md b/content/rest/markdown/markdown.md similarity index 100% rename from content/rest/markdown.md rename to content/rest/markdown/markdown.md diff --git a/content/rest/meta/index.md b/content/rest/meta/index.md new file mode 100644 index 0000000000..549cd1bdf0 --- /dev/null +++ b/content/rest/meta/index.md @@ -0,0 +1,21 @@ +--- +title: Meta +intro: >- + Use the REST API to get meta information about {% data + variables.product.product_name %}, including the IP addresses of {% data + variables.product.product_name %} services. +versions: + fpt: '*' + ghae: '*' + ghec: '*' + ghes: '*' +topics: + - API +children: + - /meta +autogenerated: rest +--- + + + + diff --git a/content/rest/meta.md b/content/rest/meta/meta.md similarity index 100% rename from content/rest/meta.md rename to content/rest/meta/meta.md diff --git a/content/rest/oauth-authorizations/index.md b/content/rest/oauth-authorizations/index.md new file mode 100644 index 0000000000..bdc3ae5971 --- /dev/null +++ b/content/rest/oauth-authorizations/index.md @@ -0,0 +1,13 @@ +--- +title: OAuth authorizations +intro: Use the REST API to manage the access {% data variables.product.prodname_oauth_app %}s have to your account. +versions: + ghes: '*' +topics: + - API +children: + - /oauth-authorizations +autogenerated: rest +--- + + diff --git a/content/rest/oauth-authorizations.md b/content/rest/oauth-authorizations/oauth-authorizations.md similarity index 100% rename from content/rest/oauth-authorizations.md rename to content/rest/oauth-authorizations/oauth-authorizations.md diff --git a/content/rest/packages/index.md b/content/rest/packages/index.md new file mode 100644 index 0000000000..b2fd5c22e4 --- /dev/null +++ b/content/rest/packages/index.md @@ -0,0 +1,17 @@ +--- +title: Packages +intro: >- + Use the REST API to interact with {% data variables.product.prodname_registry + %}. +versions: + fpt: '*' + ghec: '*' + ghes: '>=3.9' +topics: + - API +children: + - /packages +autogenerated: rest +--- + + diff --git a/content/rest/packages.md b/content/rest/packages/packages.md similarity index 100% rename from content/rest/packages.md rename to content/rest/packages/packages.md diff --git a/content/rest/pages/index.md b/content/rest/pages/index.md new file mode 100644 index 0000000000..f4b5111430 --- /dev/null +++ b/content/rest/pages/index.md @@ -0,0 +1,20 @@ +--- +title: Pages +intro: >- + Use the REST API to interact with {% data variables.product.prodname_pages %} + sites and builds. +versions: + fpt: '*' + ghae: '*' + ghec: '*' + ghes: '*' +topics: + - API +children: + - /pages +autogenerated: rest +--- + + + + diff --git a/content/rest/pages.md b/content/rest/pages/pages.md similarity index 100% rename from content/rest/pages.md rename to content/rest/pages/pages.md diff --git a/content/rest/rate-limit/index.md b/content/rest/rate-limit/index.md new file mode 100644 index 0000000000..4c3fd57116 --- /dev/null +++ b/content/rest/rate-limit/index.md @@ -0,0 +1,16 @@ +--- +title: Rate limit +intro: Use the REST API to check your current rate limit status. +versions: + fpt: '*' + ghae: '*' + ghec: '*' + ghes: '*' +topics: + - API +children: + - /rate-limit +autogenerated: rest +--- + + diff --git a/content/rest/rate-limit.md b/content/rest/rate-limit/rate-limit.md similarity index 100% rename from content/rest/rate-limit.md rename to content/rest/rate-limit/rate-limit.md diff --git a/content/rest/reactions/index.md b/content/rest/reactions/index.md new file mode 100644 index 0000000000..c38af1f8dc --- /dev/null +++ b/content/rest/reactions/index.md @@ -0,0 +1,18 @@ +--- +title: Reactions +intro: >- + Use the REST API to interact with reactions on {% data + variables.product.prodname_dotcom %}. +versions: + fpt: '*' + ghae: '*' + ghec: '*' + ghes: '*' +topics: + - API +children: + - /reactions +autogenerated: rest +--- + + diff --git a/content/rest/reactions.md b/content/rest/reactions/reactions.md similarity index 100% rename from content/rest/reactions.md rename to content/rest/reactions/reactions.md diff --git a/content/rest/scim/index.md b/content/rest/scim/index.md new file mode 100644 index 0000000000..2961a53407 --- /dev/null +++ b/content/rest/scim/index.md @@ -0,0 +1,15 @@ +--- +title: SCIM +intro: >- + Use the REST API to control and manage your GitHub organization members access + with SCIM. +versions: + ghec: '*' +topics: + - API +children: + - /scim +autogenerated: rest +--- + + diff --git a/content/rest/scim.md b/content/rest/scim/scim.md similarity index 100% rename from content/rest/scim.md rename to content/rest/scim/scim.md diff --git a/content/rest/search/index.md b/content/rest/search/index.md new file mode 100644 index 0000000000..215346359c --- /dev/null +++ b/content/rest/search/index.md @@ -0,0 +1,18 @@ +--- +title: Search +intro: >- + Use the REST API to search for specific items on {% data + variables.product.product_name %}. +versions: + fpt: '*' + ghae: '*' + ghec: '*' + ghes: '*' +topics: + - API +children: + - /search +autogenerated: rest +--- + + diff --git a/content/rest/search.md b/content/rest/search/search.md similarity index 100% rename from content/rest/search.md rename to content/rest/search/search.md diff --git a/content/rest/secret-scanning/index.md b/content/rest/secret-scanning/index.md new file mode 100644 index 0000000000..656002941c --- /dev/null +++ b/content/rest/secret-scanning/index.md @@ -0,0 +1,16 @@ +--- +title: Secret scanning +intro: Use the REST API to retrieve and update secret alerts from a repository. +versions: + fpt: '*' + ghae: '*' + ghec: '*' + ghes: '*' +topics: + - API +children: + - /secret-scanning +autogenerated: rest +--- + + diff --git a/content/rest/secret-scanning.md b/content/rest/secret-scanning/secret-scanning.md similarity index 100% rename from content/rest/secret-scanning.md rename to content/rest/secret-scanning/secret-scanning.md diff --git a/src/rest/scripts/utils/update-markdown.js b/src/rest/scripts/utils/update-markdown.js index 4d0b97463d..0193c30098 100644 --- a/src/rest/scripts/utils/update-markdown.js +++ b/src/rest/scripts/utils/update-markdown.js @@ -85,31 +85,8 @@ async function getDataFrontmatter(dataDirectory, schemaFilename) { async function getMarkdownContent(versions) { const markdownUpdates = {} - for (const category of Object.keys(versions)) { - const subcategories = Object.keys(versions[category]) - // When there is only a single subcategory and the name - // matches the category, this is an override due to a - // subcategory not being defined. In this case, - // the markdown file will be in the content/rest directory. - // The file path will be content/rest/.md - if (subcategories.length === 1 && category === subcategories[0]) { - // this will be a file in the root of the rest directory - const filepath = path.join('content/rest', `${category}.md`) - markdownUpdates[filepath] = { - data: { - title: category, - shortTitle: category, - intro: '', - versions: await convertVersionsToFrontmatter( - versions[category][subcategories[0]].versions - ), - ...frontmatterDefaults, - }, - content: '', - } - continue - } - + for (const [category, subcategoryObject] of Object.entries(versions)) { + const subcategories = Object.keys(subcategoryObject) // The file path will be content/rest//.md for (const subcategory of subcategories) { const filepath = path.join('content/rest', category, `${subcategory}.md`) diff --git a/src/rest/tests/rendering.js b/src/rest/tests/rendering.js index 06331b2982..15f31f358d 100644 --- a/src/rest/tests/rendering.js +++ b/src/rest/tests/rendering.js @@ -1,7 +1,7 @@ import { jest, test } from '@jest/globals' import { slug } from 'github-slugger' -import { getDOM } from '../../../tests/helpers/e2etest.js' +import { get, getDOM } from '../../../tests/helpers/e2etest.js' import { isApiVersioned, allVersions } from '../../../lib/all-versions.js' import { getDiffOpenAPIContentRest } from '../scripts/test-open-api-schema.js' import getRest from '#src/rest/lib/index.js' @@ -25,6 +25,59 @@ describe('REST references docs', () => { } }) + // These tests exists because of issue #1960 + test('rest subcategory with fpt in URL', async () => { + for (const category of [ + 'migrations', + 'actions', + 'activity', + 'apps', + 'billing', + 'checks', + 'codes-of-conduct', + 'code-scanning', + 'codespaces', + 'emojis', + 'gists', + 'git', + 'gitignore', + 'interactions', + 'issues', + 'licenses', + 'markdown', + 'meta', + 'orgs', + 'projects', + 'pulls', + 'rate-limit', + 'reactions', + 'repos', + 'scim', + 'search', + 'teams', + 'users', + ]) { + // Without language prefix + { + const res = await get(`/free-pro-team@latest/rest/reference/${category}`) + expect(res.statusCode).toBe(302) + expect( + res.headers.location === `/en/rest/${category}` || + res.headers.location === `/en/rest/${category}/${category}` + ) + } + // With language prefix + { + const res = await get(`/en/free-pro-team@latest/rest/reference/${category}`) + expect(res.statusCode).toBe(301) + expect( + res.headers.location === `/en/rest/${category}` || + res.headers.location === `/en/rest/${category}/${category}` + ) + } + } + }) + test('test the latest version of the OpenAPI schema categories/subcategories to see if it matches the content/rest directory', async () => { const differences = await getDiffOpenAPIContentRest() const errorMessage = formatErrors(differences) diff --git a/tests/routing/redirects.js b/tests/routing/redirects.js index a4aea53545..307defaeba 100644 --- a/tests/routing/redirects.js +++ b/tests/routing/redirects.js @@ -411,54 +411,6 @@ describe('redirects', () => { }) }) - // These tests exists because of issue #1960 - describe('rest reference redirects with default product', () => { - test('rest subcategory with fpt in URL', async () => { - for (const category of [ - 'migrations', - 'actions', - 'activity', - 'apps', - 'billing', - 'checks', - 'codes-of-conduct', - 'code-scanning', - 'codespaces', - 'emojis', - 'gists', - 'git', - 'gitignore', - 'interactions', - 'issues', - 'licenses', - 'markdown', - 'meta', - 'orgs', - 'projects', - 'pulls', - 'rate-limit', - 'reactions', - 'repos', - 'search', - 'teams', - 'users', - ]) { - // Without language prefix - { - const res = await get(`/free-pro-team@latest/rest/reference/${category}`) - expect(res.statusCode).toBe(302) - expect(res.headers.location).toBe(`/en/rest/${category}`) - } - // With language prefix - { - const res = await get(`/en/free-pro-team@latest/rest/reference/${category}`) - expect(res.statusCode).toBe(301) - expect(res.headers.location).toBe(`/en/rest/${category}`) - } - } - }) - }) - describe('redirects with double-slashes', () => { test('prefix double-slash', async () => { const res = await get(`//en`)