diff --git a/services/github/github-hacktoberfest.service.js b/services/github/github-hacktoberfest.service.js index fab20a88749dbf453b92a4d50c88810ee204dd49..c414c94228951d4d5851d09865b86f2e99a8f6e2 100644 --- a/services/github/github-hacktoberfest.service.js +++ b/services/github/github-hacktoberfest.service.js @@ -1,6 +1,7 @@ import gql from 'graphql-tag' import Joi from 'joi' import dayjs from 'dayjs' +import { pathParam, queryParam } from '../index.js' import { metric, maybePluralize } from '../text-formatters.js' import { nonNegativeInteger } from '../validators.js' import { GithubAuthV4Service } from './github-auth-service.js' @@ -9,7 +10,7 @@ import { transformErrors, } from './github-helpers.js' -const documentation = ` +const description = ` This badge is designed for projects hosted on GitHub which are participating in [Hacktoberfest](https://hacktoberfest.digitalocean.com), @@ -55,40 +56,24 @@ export default class GithubHacktoberfestCombinedStatus extends GithubAuthV4Servi queryParamSchema, } - static examples = [ - { - title: 'GitHub Hacktoberfest combined status', - namedParams: { - year: '2023', - user: 'snyk', - repo: 'snyk', + static openApi = { + '/github/hacktoberfest/{year}/{user}/{repo}': { + get: { + summary: 'GitHub Hacktoberfest combined status', + description, + parameters: [ + pathParam({ + name: 'year', + example: '2023', + schema: { type: 'string', enum: this.getEnum('year') }, + }), + pathParam({ name: 'user', example: 'tmrowco' }), + pathParam({ name: 'repo', example: 'tmrowapp-contrib' }), + queryParam({ name: 'suggestion_label', example: 'help wanted' }), + ], }, - staticPreview: this.render({ - suggestedIssueCount: 12, - contributionCount: 8, - daysLeft: 15, - }), - documentation, }, - { - title: 'GitHub Hacktoberfest combined status (suggestion label override)', - namedParams: { - year: '2023', - user: 'tmrowco', - repo: 'tmrowapp-contrib', - }, - queryParams: { - suggestion_label: 'help wanted', - }, - staticPreview: this.render({ - year: '2023', - suggestedIssueCount: 12, - contributionCount: 8, - daysLeft: 15, - }), - documentation, - }, - ] + } static defaultBadgeData = { label: 'hacktoberfest', color: 'orange' } diff --git a/services/github/github-last-commit.service.js b/services/github/github-last-commit.service.js index 100a2c9fe3a0eecc2a4e481b3217df2b42a110ee..58759c13b1b9d3da42079b3cede0c08ca09194e1 100644 --- a/services/github/github-last-commit.service.js +++ b/services/github/github-last-commit.service.js @@ -1,12 +1,9 @@ import Joi from 'joi' +import { pathParam, queryParam } from '../index.js' import { formatDate } from '../text-formatters.js' import { age as ageColor } from '../color-formatters.js' import { GithubAuthV3Service } from './github-auth-service.js' import { documentation, httpErrorsFor } from './github-helpers.js' -const commonExampleAttrs = { - keywords: ['latest'], - documentation, -} const schema = Joi.array() .items( @@ -24,9 +21,11 @@ const schema = Joi.array() .required() .min(1) +const displayEnum = ['author', 'committer'] + const queryParamSchema = Joi.object({ display_timestamp: Joi.string() - .valid('author', 'committer') + .valid(...displayEnum) .default('author'), }).required() @@ -38,40 +37,41 @@ export default class GithubLastCommit extends GithubAuthV3Service { queryParamSchema, } - static examples = [ - { - title: 'GitHub last commit', - pattern: ':user/:repo', - namedParams: { - user: 'google', - repo: 'skia', + static openApi = { + '/github/last-commit/{user}/{repo}': { + get: { + summary: 'GitHub last commit', + description: documentation, + parameters: [ + pathParam({ name: 'user', example: 'google' }), + pathParam({ name: 'repo', example: 'skia' }), + queryParam({ + name: 'display_timestamp', + example: 'committer', + schema: { type: 'string', enum: displayEnum }, + description: 'Defaults to `author` if not specified', + }), + ], }, - staticPreview: this.render({ commitDate: '2013-07-31T20:01:41Z' }), - ...commonExampleAttrs, }, - { - title: 'GitHub last commit (branch)', - pattern: ':user/:repo/:branch', - namedParams: { - user: 'google', - repo: 'skia', - branch: 'infra/config', + '/github/last-commit/{user}/{repo}/{branch}': { + get: { + summary: 'GitHub last commit (branch)', + description: documentation, + parameters: [ + pathParam({ name: 'user', example: 'google' }), + pathParam({ name: 'repo', example: 'skia' }), + pathParam({ name: 'branch', example: 'infra/config' }), + queryParam({ + name: 'display_timestamp', + example: 'committer', + schema: { type: 'string', enum: displayEnum }, + description: 'Defaults to `author` if not specified', + }), + ], }, - staticPreview: this.render({ commitDate: '2013-07-31T20:01:41Z' }), - ...commonExampleAttrs, }, - { - title: 'GitHub last commit (by committer)', - pattern: ':user/:repo', - namedParams: { - user: 'google', - repo: 'skia', - }, - queryParams: { display_timestamp: 'committer' }, - staticPreview: this.render({ commitDate: '2022-10-15T20:01:41Z' }), - ...commonExampleAttrs, - }, - ] + } static defaultBadgeData = { label: 'last commit' } diff --git a/services/github/github-manifest.service.js b/services/github/github-manifest.service.js index 59195073985974787409fac24d3f886cf2f5d74b..4d88b49f2f3a6404f77a84e2343179896dde77e6 100644 --- a/services/github/github-manifest.service.js +++ b/services/github/github-manifest.service.js @@ -1,4 +1,5 @@ import Joi from 'joi' +import { pathParam, queryParam } from '../index.js' import { renderVersionBadge } from '../version.js' import { individualValueSchema, @@ -27,56 +28,31 @@ class GithubManifestVersion extends ConditionalGithubAuthV3Service { queryParamSchema, } - static examples = [ - { - title: 'GitHub manifest version', - pattern: ':user/:repo', - namedParams: { - user: 'sindresorhus', - repo: 'show-all-github-issues', + static openApi = { + '/github/manifest-json/v/{user}/{repo}': { + get: { + summary: 'GitHub manifest version', + description: documentation, + parameters: [ + pathParam({ name: 'user', example: 'sindresorhus' }), + pathParam({ name: 'repo', example: 'show-all-github-issues' }), + queryParam({ name: 'filename', example: 'extension/manifest.json' }), + ], }, - staticPreview: this.render({ version: '1.0.3' }), - documentation, }, - { - title: 'GitHub manifest version', - pattern: ':user/:repo/:branch', - namedParams: { - user: 'sindresorhus', - repo: 'show-all-github-issues', - branch: 'master', + '/github/manifest-json/v/{user}/{repo}/{branch}': { + get: { + summary: 'GitHub manifest version (branch)', + description: documentation, + parameters: [ + pathParam({ name: 'user', example: 'sindresorhus' }), + pathParam({ name: 'repo', example: 'show-all-github-issues' }), + pathParam({ name: 'branch', example: 'master' }), + queryParam({ name: 'filename', example: 'extension/manifest.json' }), + ], }, - staticPreview: this.render({ version: '1.0.3', branch: 'master' }), - documentation, }, - { - title: 'GitHub manifest version (path)', - pattern: ':user/:repo', - namedParams: { - user: 'RedSparr0w', - repo: 'IndieGala-Helper', - }, - queryParams: { - filename: 'extension/manifest.json', - }, - staticPreview: this.render({ version: 2 }), - documentation, - }, - { - title: 'GitHub manifest version (path)', - pattern: ':user/:repo/:branch', - namedParams: { - user: 'RedSparr0w', - repo: 'IndieGala-Helper', - branch: 'master', - }, - queryParams: { - filename: 'extension/manifest.json', - }, - staticPreview: this.render({ version: 2, branch: 'master' }), - documentation, - }, - ] + } static render({ version, branch }) { return renderVersionBadge({ @@ -106,74 +82,33 @@ class DynamicGithubManifest extends ConditionalGithubAuthV3Service { queryParamSchema, } - static examples = [ - { - title: 'GitHub manifest.json dynamic', - pattern: ':key/:user/:repo', - namedParams: { - key: 'permissions', - user: 'sindresorhus', - repo: 'show-all-github-issues', + static openApi = { + '/github/manifest-json/{key}/{user}/{repo}': { + get: { + summary: 'GitHub manifest.json dynamic', + description: documentation, + parameters: [ + pathParam({ name: 'key', example: 'permissions' }), + pathParam({ name: 'user', example: 'sindresorhus' }), + pathParam({ name: 'repo', example: 'show-all-github-issues' }), + queryParam({ name: 'filename', example: 'extension/manifest.json' }), + ], }, - staticPreview: this.render({ - key: 'permissions', - value: ['webRequest', 'webRequestBlocking'], - }), - documentation, }, - { - title: 'GitHub manifest.json dynamic', - pattern: ':key/:user/:repo/:branch', - namedParams: { - key: 'permissions', - user: 'sindresorhus', - repo: 'show-all-github-issues', - branch: 'master', + '/github/manifest-json/{key}/{user}/{repo}/{branch}': { + get: { + summary: 'GitHub manifest.json dynamic (branch)', + description: documentation, + parameters: [ + pathParam({ name: 'key', example: 'permissions' }), + pathParam({ name: 'user', example: 'sindresorhus' }), + pathParam({ name: 'repo', example: 'show-all-github-issues' }), + pathParam({ name: 'branch', example: 'main' }), + queryParam({ name: 'filename', example: 'extension/manifest.json' }), + ], }, - staticPreview: this.render({ - key: 'permissions', - value: ['webRequest', 'webRequestBlocking'], - branch: 'master', - }), - documentation, }, - { - title: 'GitHub manifest.json dynamic (path)', - pattern: ':key/:user/:repo', - namedParams: { - key: 'permissions', - user: 'RedSparr0w', - repo: 'IndieGala-Helper', - }, - queryParams: { - filename: 'extension/manifest.json', - }, - staticPreview: this.render({ - key: 'permissions', - value: ['bundle', 'rollup', 'micro library'], - }), - documentation, - }, - { - title: 'GitHub manifest.json dynamic (path)', - pattern: ':key/:user/:repo/:branch', - namedParams: { - key: 'permissions', - user: 'RedSparr0w', - repo: 'IndieGala-Helper', - branch: 'master', - }, - queryParams: { - filename: 'extension/manifest.json', - }, - staticPreview: this.render({ - key: 'permissions', - value: ['bundle', 'rollup', 'micro library'], - branch: 'master', - }), - documentation, - }, - ] + } static defaultBadgeData = { label: 'manifest' } diff --git a/services/github/github-package-json.service.js b/services/github/github-package-json.service.js index b1ea3175178e8dcb447b07bbb121a244fa2d9ab9..95a8d8d6d9aa22212517fd1e04cb969906114f84 100644 --- a/services/github/github-package-json.service.js +++ b/services/github/github-package-json.service.js @@ -1,4 +1,5 @@ import Joi from 'joi' +import { pathParam, pathParams, queryParam } from '../index.js' import { renderVersionBadge } from '../version.js' import { transformAndValidate, renderDynamicBadge } from '../dynamic-common.js' import { @@ -10,8 +11,6 @@ import { ConditionalGithubAuthV3Service } from './github-auth-service.js' import { fetchJsonFromRepo } from './github-common-fetch.js' import { documentation } from './github-helpers.js' -const keywords = ['npm', 'node'] - const versionSchema = Joi.object({ version: semver, }).required() @@ -28,42 +27,31 @@ class GithubPackageJsonVersion extends ConditionalGithubAuthV3Service { queryParamSchema: subfolderQueryParamSchema, } - static examples = [ - { - title: 'GitHub package.json version', - pattern: ':user/:repo', - namedParams: { user: 'IcedFrisby', repo: 'IcedFrisby' }, - staticPreview: this.render({ version: '2.0.0-alpha.2' }), - documentation, - keywords, - }, - { - title: 'GitHub package.json version (branch)', - pattern: ':user/:repo/:branch', - namedParams: { - user: 'IcedFrisby', - repo: 'IcedFrisby', - branch: 'master', + static openApi = { + '/github/package-json/v/{user}/{repo}': { + get: { + summary: 'GitHub package.json version', + description: documentation, + parameters: [ + pathParam({ name: 'user', example: 'badges' }), + pathParam({ name: 'repo', example: 'shields' }), + queryParam({ name: 'filename', example: 'badge-maker/package.json' }), + ], }, - staticPreview: this.render({ version: '2.0.0-alpha.2' }), - documentation, - keywords, }, - { - title: 'GitHub package.json version (subfolder of monorepo)', - pattern: ':user/:repo', - namedParams: { - user: 'metabolize', - repo: 'anafanafo', - }, - queryParams: { - filename: 'packages/char-width-table-builder/package.json', + '/github/package-json/v/{user}/{repo}/{branch}': { + get: { + summary: 'GitHub package.json version (branch)', + description: documentation, + parameters: [ + pathParam({ name: 'user', example: 'badges' }), + pathParam({ name: 'repo', example: 'shields' }), + pathParam({ name: 'branch', example: 'master' }), + queryParam({ name: 'filename', example: 'badge-maker/package.json' }), + ], }, - staticPreview: this.render({ version: '2.0.0' }), - documentation, - keywords, }, - ] + } static render({ version, branch }) { return renderVersionBadge({ @@ -85,6 +73,9 @@ class GithubPackageJsonVersion extends ConditionalGithubAuthV3Service { } } +const packageNameDescription = + 'This may be the name of an unscoped package like `package-name` or a [scoped package](https://docs.npmjs.com/about-scopes) like `@author/package-name`' + class GithubPackageJsonDependencyVersion extends ConditionalGithubAuthV3Service { static category = 'platform-support' static route = { @@ -94,58 +85,100 @@ class GithubPackageJsonDependencyVersion extends ConditionalGithubAuthV3Service queryParamSchema: subfolderQueryParamSchema, } - static examples = [ - { - title: 'GitHub package.json dependency version (prod)', - pattern: ':user/:repo/:packageName', - namedParams: { - user: 'developit', - repo: 'microbundle', - packageName: 'rollup', + static openApi = { + '/github/package-json/dependency-version/{user}/{repo}/{packageName}': { + get: { + summary: 'GitHub package.json prod dependency version', + description: documentation, + parameters: [ + pathParam({ name: 'user', example: 'badges' }), + pathParam({ name: 'repo', example: 'shields' }), + pathParam({ + name: 'packageName', + example: 'dayjs', + description: packageNameDescription, + }), + queryParam({ + name: 'filename', + example: 'badge-maker/package.json', + }), + ], }, - staticPreview: this.render({ - dependency: 'rollup', - range: '^0.67.3', - }), - documentation, - keywords, }, - { - title: 'GitHub package.json dependency version (dev dep on branch)', - pattern: ':user/:repo/dev/:scope?/:packageName/:branch*', - namedParams: { - user: 'zeit', - repo: 'next.js', - branch: 'canary', - scope: '@babel', - packageName: 'preset-react', + '/github/package-json/dependency-version/{user}/{repo}/{packageName}/{branch}': + { + get: { + summary: 'GitHub package.json prod dependency version (branch)', + description: documentation, + parameters: [ + pathParam({ name: 'user', example: 'badges' }), + pathParam({ name: 'repo', example: 'shields' }), + pathParam({ + name: 'packageName', + example: 'dayjs', + description: packageNameDescription, + }), + pathParam({ name: 'branch', example: 'master' }), + queryParam({ + name: 'filename', + example: 'badge-maker/package.json', + }), + ], + }, }, - staticPreview: this.render({ - dependency: '@babel/preset-react', - range: '7.0.0', - }), - documentation, - keywords, - }, - { - title: 'GitHub package.json dependency version (subfolder of monorepo)', - pattern: ':user/:repo/:packageName', - namedParams: { - user: 'metabolize', - repo: 'anafanafo', - packageName: 'puppeteer', + '/github/package-json/dependency-version/{user}/{repo}/{kind}/{packageName}': + { + get: { + summary: 'GitHub package.json dev/peer/optional dependency version', + description: documentation, + parameters: [ + pathParam({ name: 'user', example: 'gatsbyjs' }), + pathParam({ name: 'repo', example: 'gatsby' }), + pathParam({ + name: 'kind', + example: 'dev', + schema: { type: 'string', enum: this.getEnum('kind') }, + }), + pathParam({ + name: 'packageName', + example: 'cross-env', + description: packageNameDescription, + }), + queryParam({ + name: 'filename', + example: 'packages/gatsby-cli/package.json', + }), + ], + }, }, - queryParams: { - filename: 'packages/char-width-table-builder/package.json', + '/github/package-json/dependency-version/{user}/{repo}/{kind}/{packageName}/{branch}': + { + get: { + summary: + 'GitHub package.json dev/peer/optional dependency version (branch)', + description: documentation, + parameters: [ + pathParam({ name: 'user', example: 'gatsbyjs' }), + pathParam({ name: 'repo', example: 'gatsby' }), + pathParam({ + name: 'kind', + example: 'dev', + schema: { type: 'string', enum: this.getEnum('kind') }, + }), + pathParam({ + name: 'packageName', + example: 'cross-env', + description: packageNameDescription, + }), + pathParam({ name: 'branch', example: 'master' }), + queryParam({ + name: 'filename', + example: 'packages/gatsby-cli/package.json', + }), + ], + }, }, - staticPreview: this.render({ - dependency: 'puppeteer', - range: '^1.14.0', - }), - documentation, - keywords, - }, - ] + } static defaultBadgeData = { label: 'dependency' } @@ -200,40 +233,39 @@ class DynamicGithubPackageJson extends ConditionalGithubAuthV3Service { pattern: ':key/:user/:repo/:branch*', } - static examples = [ - { - title: 'GitHub package.json dynamic', - pattern: ':key/:user/:repo', - namedParams: { - key: 'keywords', - user: 'developit', - repo: 'microbundle', + static openApi = { + '/github/package-json/{key}/{user}/{repo}': { + get: { + summary: 'GitHub package.json dynamic', + description: documentation, + parameters: pathParams( + { + name: 'key', + example: 'keywords', + description: 'any key in package.json', + }, + { name: 'user', example: 'developit' }, + { name: 'repo', example: 'microbundle' }, + ), }, - staticPreview: this.render({ - key: 'keywords', - value: ['bundle', 'rollup', 'micro library'], - }), - documentation, - keywords, }, - { - title: 'GitHub package.json dynamic', - pattern: ':key/:user/:repo/:branch', - namedParams: { - key: 'keywords', - user: 'developit', - repo: 'microbundle', - branch: 'master', + '/github/package-json/{key}/{user}/{repo}/{branch}': { + get: { + summary: 'GitHub package.json dynamic (branch)', + description: documentation, + parameters: pathParams( + { + name: 'key', + example: 'keywords', + description: 'any key in package.json', + }, + { name: 'user', example: 'developit' }, + { name: 'repo', example: 'microbundle' }, + { name: 'branch', example: 'master' }, + ), }, - staticPreview: this.render({ - key: 'keywords', - value: ['bundle', 'rollup', 'micro library'], - branch: 'master', - }), - documentation, - keywords, }, - ] + } static defaultBadgeData = { label: 'package.json' } diff --git a/services/github/github-total-star.service.js b/services/github/github-total-star.service.js index 6a2f7e52af33feaefa3276453a579ac87411cc96..26a8296fc2c716b011304dee6e8e7c3b7391232f 100644 --- a/services/github/github-total-star.service.js +++ b/services/github/github-total-star.service.js @@ -1,5 +1,6 @@ import Joi from 'joi' import gql from 'graphql-tag' +import { pathParam, queryParam } from '../index.js' import { nonNegativeInteger } from '../validators.js' import { metric } from '../text-formatters.js' import { GithubAuthV4Service } from './github-auth-service.js' @@ -10,22 +11,15 @@ import { const MAX_REPO_LIMIT = 200 -const customDocumentation = `This badge takes into account up to <code>${MAX_REPO_LIMIT}</code> of the most starred repositories of given user / org.` - -const userDocumentation = `${commonDocumentation} -<p> - <b>Note:</b><br> - 1. ${customDocumentation}<br> - 2. <code>affiliations</code> query param accepts three values (must be UPPER case) <code>OWNER</code>, <code>COLLABORATOR</code>, <code>ORGANIZATION_MEMBER</code>. - One can pass comma separated combinations of these values (no spaces) e.g. <code>OWNER,COLLABORATOR</code> or <code>OWNER,COLLABORATOR,ORGANIZATION_MEMBER</code>. - Default value is <code>OWNER</code>. See the explanation of these values <a href="https://docs.github.com/en/graphql/reference/enums#repositoryaffiliation">here</a>. -</p> -` -const orgDocumentation = `${commonDocumentation} +const description = `${commonDocumentation} <p> - <b>Note:</b> ${customDocumentation} + <b>Note:</b> This badge takes into account up to <code>${MAX_REPO_LIMIT}</code> of the most starred repositories of given user / org. </p>` +const affiliationsDescription = `This param accepts three values (must be UPPER case) <code>OWNER</code>, <code>COLLABORATOR</code>, <code>ORGANIZATION_MEMBER</code>. +One can pass comma separated combinations of these values (no spaces) e.g. <code>OWNER,COLLABORATOR</code> or <code>OWNER,COLLABORATOR,ORGANIZATION_MEMBER</code>. +Default value is <code>OWNER</code>. See the explanation of these values <a href="https://docs.github.com/en/graphql/reference/enums#repositoryaffiliation">here</a>.` + const pageInfoSchema = Joi.object({ hasNextPage: Joi.boolean().required(), endCursor: Joi.string().allow(null).required(), @@ -141,34 +135,29 @@ export default class GithubTotalStarService extends GithubAuthV4Service { queryParamSchema, } - static examples = [ - { - title: "GitHub User's stars", - namedParams: { - user: 'chris48s', + static openApi = { + '/github/stars/{user}': { + get: { + summary: "GitHub User's stars", + description, + parameters: [ + pathParam({ name: 'user', example: 'chris48s' }), + queryParam({ + name: 'affiliations', + example: 'OWNER,COLLABORATOR', + description: affiliationsDescription, + }), + ], }, - queryParams: { affiliations: 'OWNER,COLLABORATOR' }, - staticPreview: { - label: this.defaultLabel, - message: 54, - style: 'social', - }, - documentation: userDocumentation, }, - { - title: "GitHub Org's stars", - pattern: ':org', - namedParams: { - org: 'badges', - }, - staticPreview: { - label: this.defaultLabel, - message: metric(7000), - style: 'social', + '/github/stars/{org}': { + get: { + summary: "GitHub Org's stars", + description, + parameters: [pathParam({ name: 'org', example: 'badges' })], }, - documentation: orgDocumentation, }, - ] + } static defaultBadgeData = { label: this.defaultLabel,