migrate some services from examples to openApi (#9915)

services/github/github-hacktoberfest.service.js

 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',
-      },
-      staticPreview: this.render({
-        suggestedIssueCount: 12,
-        contributionCount: 8,
-        daysLeft: 15,
+  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') },
           }),
-      documentation,
-    },
-    {
-      title: 'GitHub Hacktoberfest combined status (suggestion label override)',
-      namedParams: {
-        year: '2023',
-        user: 'tmrowco',
-        repo: 'tmrowapp-contrib',
-      },
-      queryParams: {
-        suggestion_label: 'help wanted',
+          pathParam({ name: 'user', example: 'tmrowco' }),
+          pathParam({ name: 'repo', example: 'tmrowapp-contrib' }),
+          queryParam({ name: 'suggestion_label', example: 'help wanted' }),
+        ],
       },
-      staticPreview: this.render({
-        year: '2023',
-        suggestedIssueCount: 12,
-        contributionCount: 8,
-        daysLeft: 15,
-      }),
-      documentation,
     },
-  ]
+  }
 
   static defaultBadgeData = { label: 'hacktoberfest', color: 'orange' }
 

services/github/github-last-commit.service.js

 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',
-      },
-      staticPreview: this.render({ commitDate: '2013-07-31T20:01:41Z' }),
-      ...commonExampleAttrs,
+  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',
+          }),
+        ],
       },
-    {
-      title: 'GitHub last commit (branch)',
-      pattern: ':user/:repo/:branch',
-      namedParams: {
-        user: 'google',
-        repo: 'skia',
-        branch: 'infra/config',
     },
-      staticPreview: this.render({ commitDate: '2013-07-31T20:01:41Z' }),
-      ...commonExampleAttrs,
+    '/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',
+          }),
+        ],
       },
-    {
-      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' }
 

services/github/github-manifest.service.js

 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' }),
+        ],
+      },
+    },
+    '/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' }),
-      documentation,
     },
-    {
-      title: 'GitHub manifest version',
-      pattern: ':user/:repo/:branch',
-      namedParams: {
-        user: 'sindresorhus',
-        repo: 'show-all-github-issues',
-        branch: 'master',
-      },
-      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' }),
+        ],
+      },
+    },
+    '/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'],
-      }),
-      documentation,
     },
-    {
-      title: 'GitHub manifest.json dynamic',
-      pattern: ':key/:user/:repo/:branch',
-      namedParams: {
-        key: 'permissions',
-        user: 'sindresorhus',
-        repo: 'show-all-github-issues',
-        branch: 'master',
-      },
-      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' }
 

services/github/github-package-json.service.js

 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',
-      },
-      staticPreview: this.render({
-        dependency: 'rollup',
-        range: '^0.67.3',
+  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',
           }),
-      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',
     },
-      staticPreview: this.render({
-        dependency: '@babel/preset-react',
-        range: '7.0.0',
+    '/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,
             }),
-      documentation,
-      keywords,
+            pathParam({ name: 'branch', example: 'master' }),
+            queryParam({
+              name: 'filename',
+              example: 'badge-maker/package.json',
+            }),
+          ],
+        },
       },
+    '/github/package-json/dependency-version/{user}/{repo}/{kind}/{packageName}':
       {
-      title: 'GitHub package.json dependency version (subfolder of monorepo)',
-      pattern: ':user/:repo/:packageName',
-      namedParams: {
-        user: 'metabolize',
-        repo: 'anafanafo',
-        packageName: 'puppeteer',
+        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',
       },
-      staticPreview: this.render({
-        dependency: 'puppeteer',
-        range: '^1.14.0',
+    '/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') },
             }),
-      documentation,
-      keywords,
+            pathParam({
+              name: 'packageName',
+              example: 'cross-env',
+              description: packageNameDescription,
+            }),
+            pathParam({ name: 'branch', example: 'master' }),
+            queryParam({
+              name: 'filename',
+              example: 'packages/gatsby-cli/package.json',
+            }),
+          ],
         },
-  ]
+      },
+  }
 
   static defaultBadgeData = { label: 'dependency' }
 
@@ -200,40 +233,39 @@ class DynamicGithubPackageJson extends ConditionalGithubAuthV3Service {
     pattern: ':key/:user/:repo/:branch*',
   }
 
-  static examples = [
+  static openApi = {
+    '/github/package-json/{key}/{user}/{repo}': {
+      get: {
+        summary: 'GitHub package.json dynamic',
+        description: documentation,
+        parameters: pathParams(
           {
-      title: 'GitHub package.json dynamic',
-      pattern: ':key/:user/:repo',
-      namedParams: {
-        key: 'keywords',
-        user: 'developit',
-        repo: 'microbundle',
+            name: 'key',
+            example: 'keywords',
+            description: 'any key in package.json',
           },
-      staticPreview: this.render({
-        key: 'keywords',
-        value: ['bundle', 'rollup', 'micro library'],
-      }),
-      documentation,
-      keywords,
+          { name: 'user', example: 'developit' },
+          { name: 'repo', example: 'microbundle' },
+        ),
       },
+    },
+    '/github/package-json/{key}/{user}/{repo}/{branch}': {
+      get: {
+        summary: 'GitHub package.json dynamic (branch)',
+        description: documentation,
+        parameters: pathParams(
           {
-      title: 'GitHub package.json dynamic',
-      pattern: ':key/:user/:repo/:branch',
-      namedParams: {
-        key: 'keywords',
-        user: 'developit',
-        repo: 'microbundle',
-        branch: 'master',
+            name: 'key',
+            example: 'keywords',
+            description: 'any key in package.json',
           },
-      staticPreview: this.render({
-        key: 'keywords',
-        value: ['bundle', 'rollup', 'micro library'],
-        branch: 'master',
-      }),
-      documentation,
-      keywords,
+          { name: 'user', example: 'developit' },
+          { name: 'repo', example: 'microbundle' },
+          { name: 'branch', example: 'master' },
+        ),
       },
-  ]
+    },
+  }
 
   static defaultBadgeData = { label: 'package.json' }
 

services/github/github-total-star.service.js

 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',
-      },
-      queryParams: { affiliations: 'OWNER,COLLABORATOR' },
-      staticPreview: {
-        label: this.defaultLabel,
-        message: 54,
-        style: 'social',
+  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,
+          }),
+        ],
       },
-      documentation: userDocumentation,
     },
-    {
-      title: "GitHub Org's stars",
-      pattern: ':org',
-      namedParams: {
-        org: 'badges',
+    '/github/stars/{org}': {
+      get: {
+        summary: "GitHub Org's stars",
+        description,
+        parameters: [pathParam({ name: 'org', example: 'badges' })],
       },
-      staticPreview: {
-        label: this.defaultLabel,
-        message: metric(7000),
-        style: 'social',
     },
-      documentation: orgDocumentation,
-    },
-  ]
+  }
 
   static defaultBadgeData = {
     label: this.defaultLabel,