migrate examples to openApi part 16; affects [gitlabrelease swagger] (#9565)

* convert gitlab release from examples to openApi

* convert swagger from examples to openApi

* DRY up enums (1)

* DRY up enums (2)

services/gitlab/gitlab-release.service.js

 import Joi from 'joi'
 import { optionalUrl } from '../validators.js'
 import { latest, renderVersionBadge } from '../version.js'
-import { NotFound } from '../index.js'
+import { NotFound, pathParam, queryParam } from '../index.js'
 import { documentation, httpErrorsFor } from './gitlab-helper.js'
 import GitLabBase from './gitlab-base.js'
 
@@ -12,23 +12,24 @@ const schema = Joi.array().items(
   }),
 )
 
+const sortEnum = ['date', 'semver']
+const displayNameEnum = ['tag', 'release']
+const dateOrderByEnum = ['created_at', 'released_at']
+
 const queryParamSchema = Joi.object({
   gitlab_url: optionalUrl,
   include_prereleases: Joi.equal(''),
-  sort: Joi.string().valid('date', 'semver').default('date'),
-  display_name: Joi.string().valid('tag', 'release').default('tag'),
+  sort: Joi.string()
+    .valid(...sortEnum)
+    .default('date'),
+  display_name: Joi.string()
+    .valid(...displayNameEnum)
+    .default('tag'),
   date_order_by: Joi.string()
-    .valid('created_at', 'released_at')
+    .valid(...dateOrderByEnum)
     .default('created_at'),
 }).required()
 
-const commonProps = {
-  namedParams: {
-    project: 'shields-ops-group/tag-test',
-  },
-  documentation,
-}
-
 export default class GitLabRelease extends GitLabBase {
   static category = 'version'
 
@@ -38,58 +39,44 @@ export default class GitLabRelease extends GitLabBase {
     queryParamSchema,
   }
 
-  static examples = [
-    {
-      title: 'GitLab Release (latest by date)',
-      ...commonProps,
-      queryParams: { sort: 'date', date_order_by: 'created_at' },
-      staticPreview: renderVersionBadge({ version: 'v2.0.0' }),
-    },
-    {
-      title: 'GitLab Release (latest by SemVer)',
-      ...commonProps,
-      queryParams: { sort: 'semver' },
-      staticPreview: renderVersionBadge({ version: 'v4.0.0' }),
-    },
-    {
-      title: 'GitLab Release (latest by SemVer pre-release)',
-      ...commonProps,
-      queryParams: {
-        sort: 'semver',
-        include_prereleases: null,
+  static openApi = {
+    '/gitlab/v/release/{project}': {
+      get: {
+        summary: 'GitLab Release',
+        description: documentation,
+        parameters: [
+          pathParam({
+            name: 'project',
+            example: 'gitlab-org/gitlab',
+          }),
+          queryParam({
+            name: 'gitlab_url',
+            example: 'https://gitlab.com',
+          }),
+          queryParam({
+            name: 'include_prereleases',
+            schema: { type: 'boolean' },
+            example: null,
+          }),
+          queryParam({
+            name: 'sort',
+            schema: { type: 'string', enum: sortEnum },
+            example: 'semver',
+          }),
+          queryParam({
+            name: 'display_name',
+            schema: { type: 'string', enum: displayNameEnum },
+            example: 'release',
+          }),
+          queryParam({
+            name: 'date_order_by',
+            schema: { type: 'string', enum: dateOrderByEnum },
+            example: 'created_at',
+          }),
+        ],
       },
-      staticPreview: renderVersionBadge({ version: 'v5.0.0-beta.1' }),
     },
-    {
-      title: 'GitLab Release (self-managed)',
-      namedParams: {
-        project: 'GNOME/librsvg',
-      },
-      documentation,
-      queryParams: {
-        sort: 'semver',
-        include_prereleases: null,
-        gitlab_url: 'https://gitlab.gnome.org',
-        date_order_by: 'created_at',
-      },
-      staticPreview: renderVersionBadge({ version: 'v2.51.4' }),
-    },
-    {
-      title: 'GitLab Release (by release name)',
-      namedParams: {
-        project: 'gitlab-org/gitlab',
-      },
-      documentation,
-      queryParams: {
-        sort: 'semver',
-        include_prereleases: null,
-        gitlab_url: 'https://gitlab.com',
-        display_name: 'release',
-        date_order_by: 'created_at',
-      },
-      staticPreview: renderVersionBadge({ version: 'GitLab 14.2' }),
-    },
-  ]
+  }
 
   static defaultBadgeData = { label: 'release' }
 

services/swagger/swagger.service.js

 import Joi from 'joi'
 import { optionalUrl } from '../validators.js'
-import { BaseJsonService, NotFound } from '../index.js'
+import { BaseJsonService, NotFound, queryParams } from '../index.js'
 
 const schema = Joi.object()
   .keys({
@@ -26,17 +26,19 @@ export default class SwaggerValidatorService extends BaseJsonService {
     queryParamSchema,
   }
 
-  static examples = [
-    {
-      title: 'Swagger Validator',
-      staticPreview: this.render({ status: 'valid' }),
-      namedParams: {},
-      queryParams: {
-        specUrl:
-          'https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v2.0/json/petstore-expanded.json',
+  static openApi = {
+    '/swagger/valid/3.0': {
+      get: {
+        summary: 'Swagger Validator',
+        parameters: queryParams({
+          name: 'specUrl',
+          required: true,
+          example:
+            'https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v2.0/json/petstore-expanded.json',
+        }),
       },
     },
-  ]
+  }
 
   static defaultBadgeData = {
     label: 'swagger',