migrate some services from examples to openApi (#9903)

services/codecov/codecov.service.js

@@ -1,6 +1,6 @@
 import Joi from 'joi'
 import { coveragePercentage } from '../color-formatters.js'
-import { BaseSvgScrapingService } from '../index.js'
+import { BaseSvgScrapingService, pathParam, queryParam } from '../index.js'
 import { parseJson } from '../../core/base-service/json.js'
 
 // https://docs.codecov.io/reference#totals
@@ -35,12 +35,12 @@ const svgValueMatcher = />(\d{1,3}%|unknown)<\/text><\/g>/
 
 const badgeTokenPattern = /^\w{10}$/
 
-const documentation = `
+const description = `
   <p>
     You may specify a Codecov badge token to get coverage for a private repository.
   </p>
   <p>
-  You can find the token under the badge section of your project settings page, in this url: <code>https://codecov.io/{vcsName}/{user}/{repo}/settings/badge</code>.
+  You can find the token under the badge section of your project settings page, in this url: <code>https://codecov.io/&#60;vcsName&#62;/&#60;user&#62;/&#60;repo&#62;/settings/badge</code>.
   </p>
 `
 
@@ -54,39 +54,43 @@ export default class Codecov extends BaseSvgScrapingService {
     queryParamSchema,
   }
 
-  static examples = [
-    {
-      title: 'Codecov',
-      pattern: ':vcsName(github|gh|bitbucket|bb|gl|gitlab)/:user/:repo',
-      namedParams: {
-        vcsName: 'github',
-        user: 'codecov',
-        repo: 'example-node',
+  static openApi = {
+    '/codecov/c/{vcsName}/{user}/{repo}': {
+      get: {
+        summary: 'Codecov',
+        description,
+        parameters: [
+          pathParam({
+            name: 'vcsName',
+            example: 'github',
+            schema: { type: 'string', enum: this.getEnum('vcsName') },
+          }),
+          pathParam({ name: 'user', example: 'codecov' }),
+          pathParam({ name: 'repo', example: 'example-node' }),
+          queryParam({ name: 'token', example: 'a1b2c3d4e5' }),
+          queryParam({ name: 'flag', example: 'flag_name' }),
+        ],
       },
-      queryParams: {
-        token: 'a1b2c3d4e5',
-        flag: 'flag_name',
-      },
-      staticPreview: this.render({ coverage: 90 }),
-      documentation,
     },
-    {
-      title: 'Codecov branch',
-      pattern: ':vcsName(github|gh|bitbucket|bb|gl|gitlab)/:user/:repo/:branch',
-      namedParams: {
-        vcsName: 'github',
-        user: 'codecov',
-        repo: 'example-node',
-        branch: 'master',
-      },
-      queryParams: {
-        token: 'a1b2c3d4e5',
-        flag: 'flag_name',
+    '/codecov/c/{vcsName}/{user}/{repo}/{branch}': {
+      get: {
+        summary: 'Codecov (with branch)',
+        description,
+        parameters: [
+          pathParam({
+            name: 'vcsName',
+            example: 'github',
+            schema: { type: 'string', enum: this.getEnum('vcsName') },
+          }),
+          pathParam({ name: 'user', example: 'codecov' }),
+          pathParam({ name: 'repo', example: 'example-node' }),
+          pathParam({ name: 'branch', example: 'master' }),
+          queryParam({ name: 'token', example: 'a1b2c3d4e5' }),
+          queryParam({ name: 'flag', example: 'flag_name' }),
+        ],
       },
-      staticPreview: this.render({ coverage: 90 }),
-      documentation,
     },
-  ]
+  }
 
   static defaultBadgeData = { label: 'coverage' }
 

services/obs/obs.service.js

@@ -1,5 +1,5 @@
 import Joi from 'joi'
-import { BaseXmlService } from '../index.js'
+import { BaseXmlService, pathParam, queryParam } from '../index.js'
 import { optionalUrl } from '../validators.js'
 import { isBuildStatus, renderBuildStatusBadge } from './obs-build-status.js'
 
@@ -26,23 +26,22 @@ export default class ObsService extends BaseXmlService {
     isRequired: true,
   }
 
-  static examples = [
-    {
-      title: 'OBS package build status',
-      namedParams: {
-        project: 'openSUSE:Tools',
-        packageName: 'osc',
-        repository: 'Debian_11',
-        arch: 'x86_64',
+  static openApi = {
+    '/obs/{project}/{packageName}/{repository}/{arch}': {
+      get: {
+        summary: 'OBS package build status',
+        description:
+          '[Open Build Service](https://openbuildservice.org/) (OBS) is a generic system to build and distribute binary packages',
+        parameters: [
+          pathParam({ name: 'project', example: 'openSUSE:Tools' }),
+          pathParam({ name: 'packageName', example: 'osc' }),
+          pathParam({ name: 'repository', example: 'Debian_11' }),
+          pathParam({ name: 'arch', example: 'x86_64' }),
+          queryParam({ name: 'instance', example: 'https://api.opensuse.org' }),
+        ],
       },
-      queryParams: { instance: 'https://api.opensuse.org' },
-      staticPreview: this.render({
-        repository: 'Debian_11',
-        status: 'succeeded',
-      }),
-      keywords: ['open build service'],
     },
-  ]
+  }
 
   static defaultBadgeData = { label: 'build' }
 

services/scrutinizer/scrutinizer-build.service.js

@@ -1,5 +1,6 @@
 import Joi from 'joi'
 import { isBuildStatus, renderBuildStatusBadge } from '../build-status.js'
+import { pathParams } from '../index.js'
 import ScrutinizerBase from './scrutinizer-base.js'
 
 const schema = Joi.object({
@@ -38,19 +39,39 @@ class ScrutinizerBuild extends ScrutinizerBuildBase {
     pattern: ':vcs(g|b)/:user/:repo/:branch*',
   }
 
-  static examples = [
-    {
-      title: 'Scrutinizer build (GitHub/Bitbucket)',
-      pattern: ':vcs(g|b)/:user/:repo/:branch?',
-      namedParams: {
-        vcs: 'g',
-        user: 'filp',
-        repo: 'whoops',
-        branch: 'master',
+  static openApi = {
+    '/scrutinizer/build/{vcs}/{user}/{repo}': {
+      get: {
+        summary: 'Scrutinizer build (GitHub/Bitbucket)',
+        parameters: pathParams(
+          {
+            name: 'vcs',
+            example: 'g',
+            description: 'Platform: Either Github or Bitbucket',
+            schema: { type: 'string', enum: this.getEnum('vcs') },
+          },
+          { name: 'user', example: 'filp' },
+          { name: 'repo', example: 'whoops' },
+        ),
       },
-      staticPreview: renderBuildStatusBadge({ status: 'passing' }),
     },
-  ]
+    '/scrutinizer/build/{vcs}/{user}/{repo}/{branch}': {
+      get: {
+        summary: 'Scrutinizer build (GitHub/Bitbucket) with branch',
+        parameters: pathParams(
+          {
+            name: 'vcs',
+            example: 'g',
+            description: 'Platform: Either Github or Bitbucket',
+            schema: { type: 'string', enum: this.getEnum('vcs') },
+          },
+          { name: 'user', example: 'filp' },
+          { name: 'repo', example: 'whoops' },
+          { name: 'branch', example: 'master' },
+        ),
+      },
+    },
+  }
 
   async handle({ vcs, user, repo, branch }) {
     return this.makeBadge({
@@ -71,19 +92,29 @@ class ScrutinizerGitLabBuild extends ScrutinizerBuildBase {
   // The example used is valid, but the project will not be accessible if Shields users try to use it.
   // https://gitlab.propertywindow.nl/propertywindow/client
   // https://scrutinizer-ci.com/gl/propertywindow/propertywindow/client/badges/quality-score.png?b=master&s=dfae6992a48184cc2333b4c349cec0447f0d67c2
-  static examples = [
-    {
-      title: 'Scrutinizer build (GitLab)',
-      pattern: ':instance/:user/:repo/:branch?',
-      namedParams: {
-        instance: 'propertywindow',
-        user: 'propertywindow',
-        repo: 'client',
-        branch: 'master',
+  static openApi = {
+    '/scrutinizer/build/gl/{instance}/{user}/{repo}': {
+      get: {
+        summary: 'Scrutinizer build (GitLab)',
+        parameters: pathParams(
+          { name: 'instance', example: 'propertywindow' },
+          { name: 'user', example: 'propertywindow' },
+          { name: 'repo', example: 'client' },
+        ),
       },
-      staticPreview: renderBuildStatusBadge({ status: 'passing' }),
     },
-  ]
+    '/scrutinizer/build/gl/{instance}/{user}/{repo}/{branch}': {
+      get: {
+        summary: 'Scrutinizer build (GitLab) with branch',
+        parameters: pathParams(
+          { name: 'instance', example: 'propertywindow' },
+          { name: 'user', example: 'propertywindow' },
+          { name: 'repo', example: 'client' },
+          { name: 'branch', example: 'master' },
+        ),
+      },
+    },
+  }
 
   async handle({ instance, user, repo, branch }) {
     return this.makeBadge({

services/scrutinizer/scrutinizer-coverage.service.js

@@ -1,6 +1,6 @@
 import Joi from 'joi'
 import { colorScale } from '../color-formatters.js'
-import { NotFound } from '../index.js'
+import { NotFound, pathParams } from '../index.js'
 import ScrutinizerBase from './scrutinizer-base.js'
 
 const schema = Joi.object({
@@ -70,19 +70,39 @@ class ScrutinizerCoverage extends ScrutinizerCoverageBase {
     pattern: ':vcs(g|b)/:user/:repo/:branch*',
   }
 
-  static examples = [
-    {
-      title: 'Scrutinizer coverage (GitHub/BitBucket)',
-      pattern: ':vcs(g|b)/:user/:repo/:branch?',
-      namedParams: {
-        vcs: 'g',
-        user: 'filp',
-        repo: 'whoops',
-        branch: 'master',
+  static openApi = {
+    '/scrutinizer/coverage/{vcs}/{user}/{repo}': {
+      get: {
+        summary: 'Scrutinizer coverage (GitHub/Bitbucket)',
+        parameters: pathParams(
+          {
+            name: 'vcs',
+            example: 'g',
+            description: 'Platform: Either Github or Bitbucket',
+            schema: { type: 'string', enum: this.getEnum('vcs') },
+          },
+          { name: 'user', example: 'filp' },
+          { name: 'repo', example: 'whoops' },
+        ),
       },
-      staticPreview: this.render({ coverage: 86 }),
     },
-  ]
+    '/scrutinizer/coverage/{vcs}/{user}/{repo}/{branch}': {
+      get: {
+        summary: 'Scrutinizer coverage (GitHub/Bitbucket) with branch',
+        parameters: pathParams(
+          {
+            name: 'vcs',
+            example: 'g',
+            description: 'Platform: Either Github or Bitbucket',
+            schema: { type: 'string', enum: this.getEnum('vcs') },
+          },
+          { name: 'user', example: 'filp' },
+          { name: 'repo', example: 'whoops' },
+          { name: 'branch', example: 'master' },
+        ),
+      },
+    },
+  }
 
   async handle({ vcs, user, repo, branch }) {
     return this.makeBadge({
@@ -103,19 +123,29 @@ class ScrutinizerCoverageGitLab extends ScrutinizerCoverageBase {
   // The example used is valid, but the project will not be accessible if Shields users try to use it.
   // https://gitlab.propertywindow.nl/propertywindow/client
   // https://scrutinizer-ci.com/gl/propertywindow/propertywindow/client/badges/quality-score.png?b=master&s=dfae6992a48184cc2333b4c349cec0447f0d67c2
-  static examples = [
-    {
-      title: 'Scrutinizer coverage (GitLab)',
-      pattern: ':instance/:user/:repo/:branch?',
-      namedParams: {
-        instance: 'propertywindow',
-        user: 'propertywindow',
-        repo: 'client',
-        branch: 'master',
+  static openApi = {
+    '/scrutinizer/coverage/gl/{instance}/{user}/{repo}': {
+      get: {
+        summary: 'Scrutinizer coverage (GitLab)',
+        parameters: pathParams(
+          { name: 'instance', example: 'propertywindow' },
+          { name: 'user', example: 'propertywindow' },
+          { name: 'repo', example: 'client' },
+        ),
       },
-      staticPreview: this.render({ coverage: 94 }),
     },
-  ]
+    '/scrutinizer/coverage/gl/{instance}/{user}/{repo}/{branch}': {
+      get: {
+        summary: 'Scrutinizer coverage (GitLab) with branch',
+        parameters: pathParams(
+          { name: 'instance', example: 'propertywindow' },
+          { name: 'user', example: 'propertywindow' },
+          { name: 'repo', example: 'client' },
+          { name: 'branch', example: 'master' },
+        ),
+      },
+    },
+  }
 
   async handle({ instance, user, repo, branch }) {
     return this.makeBadge({