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-tag.service.js

@@ -4,9 +4,12 @@ import { matcher } from 'matcher'
 import { addv } from '../text-formatters.js'
 import { version as versionColor } from '../color-formatters.js'
 import { latest } from '../version.js'
-import { NotFound, redirector } from '../index.js'
+import { NotFound, redirector, pathParam } from '../index.js'
 import { GithubAuthV4Service } from './github-auth-service.js'
-import { filterDocs, queryParamSchema } from './github-common-release.js'
+import {
+  queryParamSchema,
+  openApiQueryParams,
+} from './github-common-release.js'
 import { documentation, transformErrors } from './github-helpers.js'
 
 const schema = Joi.object({
@@ -34,44 +37,19 @@ class GithubTag extends GithubAuthV4Service {
     queryParamSchema,
   }
 
-  static examples = [
-    {
-      title: 'GitHub tag (latest by date)',
-      namedParams: { user: 'expressjs', repo: 'express' },
-      staticPreview: this.render({
-        version: 'v5.0.0-alpha.7',
-        sort: 'date',
-      }),
-      documentation,
+  static openApi = {
+    '/github/v/tag/{user}/{repo}': {
+      get: {
+        summary: 'GitHub Tag',
+        description: documentation,
+        parameters: [
+          pathParam({ name: 'user', example: 'expressjs' }),
+          pathParam({ name: 'repo', example: 'express' }),
+          ...openApiQueryParams,
+        ],
+      },
     },
-    {
-      title: 'GitHub tag (latest SemVer)',
-      namedParams: { user: 'expressjs', repo: 'express' },
-      queryParams: { sort: 'semver' },
-      staticPreview: this.render({ version: 'v4.16.4', sort: 'semver' }),
-      documentation,
-    },
-    {
-      title: 'GitHub tag (latest SemVer pre-release)',
-      namedParams: { user: 'expressjs', repo: 'express' },
-      queryParams: { sort: 'semver', include_prereleases: null },
-      staticPreview: this.render({
-        version: 'v5.0.0-alpha.7',
-        sort: 'semver',
-      }),
-      documentation,
-    },
-    {
-      title: 'GitHub tag (with filter)',
-      namedParams: { user: 'badges', repo: 'shields' },
-      queryParams: { filter: '!server-*' },
-      staticPreview: this.render({
-        version: 'v3.3.1',
-        sort: 'date',
-      }),
-      documentation: documentation + filterDocs,
-    },
-  ]
+  }
 
   static defaultBadgeData = {
     label: 'tag',