migrate examples to openApi part 34; affects [github] (#9865)

* fix github service tests

* migrate some services from examples to openApi

* document latest variant with separate examples

making seperate routes for the /{version} and /latest variants
allows us to only show the docs for
- include_prereleases
- sort and
- filter
in the situation where they are relevant

services/github/github-actions-workflow-status.service.js

@@ -1,6 +1,6 @@
 import Joi from 'joi'
 import { isBuildStatus, renderBuildStatusBadge } from '../build-status.js'
-import { BaseSvgScrapingService } from '../index.js'
+import { BaseSvgScrapingService, pathParam, queryParam } from '../index.js'
 import { documentation } from './github-helpers.js'
 
 const schema = Joi.object({
@@ -14,8 +14,6 @@ const queryParamSchema = Joi.object({
   branch: Joi.alternatives().try(Joi.string(), Joi.number().cast('string')),
 }).required()
 
-const keywords = ['action', 'actions']
-
 export default class GithubActionsWorkflowStatus extends BaseSvgScrapingService {
   static category = 'build'
 
@@ -25,53 +23,26 @@ export default class GithubActionsWorkflowStatus extends BaseSvgScrapingService
     queryParamSchema,
   }
 
-  static examples = [
-    {
-      title: 'GitHub Workflow Status',
-      namedParams: {
-        user: 'actions',
-        repo: 'toolkit',
-        workflow: 'unit-tests.yml',
-      },
-      staticPreview: renderBuildStatusBadge({
-        status: 'passing',
-      }),
-      documentation,
-      keywords,
-    },
-    {
-      title: 'GitHub Workflow Status (with branch)',
-      namedParams: {
-        user: 'actions',
-        repo: 'toolkit',
-        workflow: 'unit-tests.yml',
-      },
-      queryParams: {
-        branch: 'main',
+  static openApi = {
+    '/github/actions/workflow/status/{user}/{repo}/{workflow}': {
+      get: {
+        summary: 'GitHub Actions Workflow Status',
+        description: documentation,
+        parameters: [
+          pathParam({ name: 'user', example: 'actions' }),
+          pathParam({ name: 'repo', example: 'toolkit' }),
+          pathParam({ name: 'workflow', example: 'unit-tests.yml' }),
+          queryParam({ name: 'branch', example: 'main' }),
+          queryParam({
+            name: 'event',
+            example: 'push',
+            description:
+              'See GitHub Actions [Events that trigger workflows](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows) for allowed values.',
+          }),
+        ],
       },
-      staticPreview: renderBuildStatusBadge({
-        status: 'passing',
-      }),
-      documentation,
-      keywords,
     },
-    {
-      title: 'GitHub Workflow Status (with event)',
-      namedParams: {
-        user: 'actions',
-        repo: 'toolkit',
-        workflow: 'unit-tests.yml',
-      },
-      queryParams: {
-        event: 'push',
-      },
-      staticPreview: renderBuildStatusBadge({
-        status: 'passing',
-      }),
-      documentation,
-      keywords,
-    },
-  ]
+  }
 
   static _cacheLength = 60
 

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

@@ -1,7 +1,7 @@
 import gql from 'graphql-tag'
 import Joi from 'joi'
 import parseLinkHeader from 'parse-link-header'
-import { InvalidResponse } from '../index.js'
+import { InvalidResponse, pathParam, queryParam } from '../index.js'
 import { metric } from '../text-formatters.js'
 import { nonNegativeInteger } from '../validators.js'
 import { GithubAuthV4Service } from './github-auth-service.js'
@@ -35,33 +35,51 @@ export default class GitHubCommitActivity extends GithubAuthV4Service {
     queryParamSchema,
   }
 
-  static examples = [
-    {
-      title: 'GitHub commit activity',
-      // Override the pattern to omit the deprecated interval "4w".
-      pattern: ':interval(t|y|m|w)/:user/:repo',
-      namedParams: { interval: 'm', user: 'eslint', repo: 'eslint' },
-      queryParams: { authorFilter: 'nzakas' },
-      staticPreview: this.render({ interval: 'm', commitCount: 457 }),
-      keywords: ['commits'],
-      documentation,
+  static openApi = {
+    '/github/commit-activity/{interval}/{user}/{repo}': {
+      get: {
+        summary: 'GitHub commit activity',
+        description: documentation,
+        parameters: [
+          pathParam({
+            name: 'interval',
+            example: 'm',
+            description: 'Commits in the last Week, Month, Year, or Total',
+            schema: {
+              type: 'string',
+              // Override the enum to omit the deprecated interval "4w".
+              enum: ['w', 'm', 'y', 't'],
+            },
+          }),
+          pathParam({ name: 'user', example: 'badges' }),
+          pathParam({ name: 'repo', example: 'squint' }),
+          queryParam({ name: 'authorFilter', example: 'calebcartwright' }),
+        ],
+      },
     },
-    {
-      title: 'GitHub commit activity (branch)',
-      // Override the pattern to omit the deprecated interval "4w".
-      pattern: ':interval(t|y|m|w)/:user/:repo/:branch*',
-      namedParams: {
-        interval: 'm',
-        user: 'badges',
-        repo: 'squint',
-        branch: 'main',
+    '/github/commit-activity/{interval}/{user}/{repo}/{branch}': {
+      get: {
+        summary: 'GitHub commit activity (branch)',
+        description: documentation,
+        parameters: [
+          pathParam({
+            name: 'interval',
+            example: 'm',
+            description: 'Commits in the last Week, Month, Year, or Total',
+            schema: {
+              type: 'string',
+              // Override the enum to omit the deprecated interval "4w".
+              enum: ['w', 'm', 'y', 't'],
+            },
+          }),
+          pathParam({ name: 'user', example: 'badges' }),
+          pathParam({ name: 'repo', example: 'squint' }),
+          pathParam({ name: 'branch', example: 'main' }),
+          queryParam({ name: 'authorFilter', example: 'calebcartwright' }),
+        ],
       },
-      queryParams: { authorFilter: 'calebcartwright' },
-      staticPreview: this.render({ interval: 'm', commitCount: 5 }),
-      keywords: ['commits'],
-      documentation,
     },
-  ]
+  }
 
   static defaultBadgeData = { label: 'commit activity', color: 'blue' }
 

services/github/github-commits-since.service.js

@@ -1,15 +1,20 @@
 import Joi from 'joi'
+import { pathParam } from '../index.js'
 import { metric } from '../text-formatters.js'
 import { nonNegativeInteger } from '../validators.js'
 import { GithubAuthV3Service } from './github-auth-service.js'
 import {
   fetchLatestRelease,
   queryParamSchema,
+  openApiQueryParams,
 } from './github-common-release.js'
 import { documentation, httpErrorsFor } from './github-helpers.js'
 
 const schema = Joi.object({ ahead_by: nonNegativeInteger }).required()
 
+const latestDocs =
+  '<p>The <code>include_prereleases</code>, <code>sort</code> and <code>filter</code> params can be used to configure how we determine the latest version.</p>'
+
 export default class GithubCommitsSince extends GithubAuthV3Service {
   static category = 'activity'
   static route = {
@@ -18,110 +23,60 @@ export default class GithubCommitsSince extends GithubAuthV3Service {
     queryParamSchema,
   }
 
-  static examples = [
-    {
-      title: 'GitHub commits since tagged version',
-      namedParams: {
-        user: 'SubtitleEdit',
-        repo: 'subtitleedit',
-        version: '3.4.7',
-      },
-      staticPreview: this.render({
-        version: '3.4.7',
-        commitCount: 4225,
-      }),
-      documentation,
-    },
-    {
-      title: 'GitHub commits since tagged version (branch)',
-      namedParams: {
-        user: 'SubtitleEdit',
-        repo: 'subtitleedit',
-        version: '3.4.7',
-        branch: 'master',
-      },
-      staticPreview: this.render({
-        version: '3.4.7',
-        commitCount: 4225,
-      }),
-      documentation,
-    },
-    {
-      title: 'GitHub commits since latest release (by date)',
-      namedParams: {
-        user: 'SubtitleEdit',
-        repo: 'subtitleedit',
-        version: 'latest',
-      },
-      staticPreview: this.render({
-        version: '3.5.7',
-        commitCount: 157,
-      }),
-      documentation,
-    },
-    {
-      title: 'GitHub commits since latest release (by date) for a branch',
-      namedParams: {
-        user: 'SubtitleEdit',
-        repo: 'subtitleedit',
-        version: 'latest',
-        branch: 'master',
+  static openApi = {
+    '/github/commits-since/{user}/{repo}/{version}': {
+      get: {
+        summary: 'GitHub commits since tagged version',
+        description: documentation,
+        parameters: [
+          pathParam({ name: 'user', example: 'SubtitleEdit' }),
+          pathParam({ name: 'repo', example: 'subtitleedit' }),
+          pathParam({
+            name: 'version',
+            example: '3.4.7',
+          }),
+        ],
       },
-      staticPreview: this.render({
-        version: '3.5.7',
-        commitCount: 157,
-      }),
-      documentation,
     },
-    {
-      title:
-        'GitHub commits since latest release (by date including pre-releases)',
-      namedParams: {
-        user: 'SubtitleEdit',
-        repo: 'subtitleedit',
-        version: 'latest',
+    '/github/commits-since/{user}/{repo}/{version}/{branch}': {
+      get: {
+        summary: 'GitHub commits since tagged version (branch)',
+        description: documentation,
+        parameters: [
+          pathParam({ name: 'user', example: 'SubtitleEdit' }),
+          pathParam({ name: 'repo', example: 'subtitleedit' }),
+          pathParam({
+            name: 'version',
+            example: '3.4.7',
+          }),
+          pathParam({ name: 'branch', example: 'main' }),
+        ],
       },
-      queryParams: { include_prereleases: null },
-      staticPreview: this.render({
-        version: 'v3.5.8-alpha.1',
-        isPrerelease: true,
-        commitCount: 158,
-      }),
-      documentation,
     },
-    {
-      title: 'GitHub commits since latest release (by SemVer)',
-      namedParams: {
-        user: 'SubtitleEdit',
-        repo: 'subtitleedit',
-        version: 'latest',
+    '/github/commits-since/{user}/{repo}/latest': {
+      get: {
+        summary: 'GitHub commits since latest release',
+        description: documentation + latestDocs,
+        parameters: [
+          pathParam({ name: 'user', example: 'SubtitleEdit' }),
+          pathParam({ name: 'repo', example: 'subtitleedit' }),
+          ...openApiQueryParams,
+        ],
       },
-      queryParams: { sort: 'semver' },
-      staticPreview: this.render({
-        version: 'v4.0.1',
-        sort: 'semver',
-        commitCount: 200,
-      }),
-      documentation,
     },
-    {
-      title:
-        'GitHub commits since latest release (by SemVer including pre-releases)',
-      namedParams: {
-        user: 'SubtitleEdit',
-        repo: 'subtitleedit',
-        version: 'latest',
+    '/github/commits-since/{user}/{repo}/latest/{branch}': {
+      get: {
+        summary: 'GitHub commits since latest release (branch)',
+        description: documentation + latestDocs,
+        parameters: [
+          pathParam({ name: 'user', example: 'SubtitleEdit' }),
+          pathParam({ name: 'repo', example: 'subtitleedit' }),
+          pathParam({ name: 'branch', example: 'main' }),
+          ...openApiQueryParams,
+        ],
       },
-      queryParams: { sort: 'semver', include_prereleases: null },
-      staticPreview: this.render({
-        version: 'v4.0.2-alpha.1',
-        sort: 'semver',
-        isPrerelease: true,
-        commitCount: 201,
-      }),
-      documentation,
     },
-  ]
+  }
 
   static defaultBadgeData = { label: 'github', namedLogo: 'github' }