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-go-mod.service.js

@@ -1,6 +1,6 @@
 import Joi from 'joi'
 import { renderVersionBadge } from '../version.js'
-import { InvalidResponse } from '../index.js'
+import { InvalidResponse, pathParam, queryParam } from '../index.js'
 import { ConditionalGithubAuthV3Service } from './github-auth-service.js'
 import { fetchRepoContent } from './github-common-fetch.js'
 import { documentation } from './github-helpers.js'
@@ -11,7 +11,8 @@ const queryParamSchema = Joi.object({
 
 const goVersionRegExp = /^go (.+)$/m
 
-const keywords = ['golang']
+const filenameDescription =
+  'The `filename` param can be used to specify the path to `go.mod`. By default, we look for `go.mod` in the repo root'
 
 export default class GithubGoModGoVersion extends ConditionalGithubAuthV3Service {
   static category = 'version'
@@ -21,42 +22,39 @@ export default class GithubGoModGoVersion extends ConditionalGithubAuthV3Service
     queryParamSchema,
   }
 
-  static examples = [
-    {
-      title: 'GitHub go.mod Go version',
-      pattern: ':user/:repo',
-      namedParams: { user: 'gohugoio', repo: 'hugo' },
-      staticPreview: this.render({ version: '1.12' }),
-      documentation,
-      keywords,
+  static openApi = {
+    '/github/go-mod/go-version/{user}/{repo}': {
+      get: {
+        summary: 'GitHub go.mod Go version',
+        description: documentation,
+        parameters: [
+          pathParam({ name: 'user', example: 'gohugoio' }),
+          pathParam({ name: 'repo', example: 'hugo' }),
+          queryParam({
+            name: 'filename',
+            example: 'src/go.mod',
+            description: filenameDescription,
+          }),
+        ],
+      },
     },
-    {
-      title: 'GitHub go.mod Go version (branch)',
-      pattern: ':user/:repo/:branch',
-      namedParams: { user: 'gohugoio', repo: 'hugo', branch: 'master' },
-      staticPreview: this.render({ version: '1.12', branch: 'master' }),
-      documentation,
-      keywords,
+    '/github/go-mod/go-version/{user}/{repo}/{branch}': {
+      get: {
+        summary: 'GitHub go.mod Go version (branch)',
+        description: documentation,
+        parameters: [
+          pathParam({ name: 'user', example: 'gohugoio' }),
+          pathParam({ name: 'repo', example: 'hugo' }),
+          pathParam({ name: 'branch', example: 'master' }),
+          queryParam({
+            name: 'filename',
+            example: 'src/go.mod',
+            description: filenameDescription,
+          }),
+        ],
+      },
     },
-    {
-      title: 'GitHub go.mod Go version (subdirectory of monorepo)',
-      pattern: ':user/:repo',
-      namedParams: { user: 'golang', repo: 'go' },
-      queryParams: { filename: 'src/go.mod' },
-      staticPreview: this.render({ version: '1.14' }),
-      documentation,
-      keywords,
-    },
-    {
-      title: 'GitHub go.mod Go version (branch & subdirectory of monorepo)',
-      pattern: ':user/:repo/:branch',
-      namedParams: { user: 'golang', repo: 'go', branch: 'master' },
-      queryParams: { filename: 'src/go.mod' },
-      staticPreview: this.render({ version: '1.14' }),
-      documentation,
-      keywords,
-    },
-  ]
+  }
 
   static defaultBadgeData = { label: 'Go' }