migrate some services from examples to openApi (#9903)

2024-01-24 20:23:12 +00:00
parent 609775ee25
commit bc41c409ff
6 changed files with 239 additions and 140 deletions
--- a/services/codecov/codecov.service.js
+++ b/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',
+    '/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' }),
+        ],
      },
-      queryParams: {
-        token: 'a1b2c3d4e5',
-        flag: 'flag_name',
-      },
-      staticPreview: this.render({ coverage: 90 }),
-      documentation,
    },
-  ]
+  }

  static defaultBadgeData = { label: 'coverage' }

--- a/services/obs/obs.service.js
+++ b/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' }

--- a/services/scrutinizer/scrutinizer-build.service.js
+++ b/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({
--- a/services/scrutinizer/scrutinizer-coverage.service.js
+++ b/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({
--- a/services/scrutinizer/scrutinizer-quality.service.js
+++ b/services/scrutinizer/scrutinizer-quality.service.js
@@ -1,5 +1,6 @@
 import Joi from 'joi'
 import { colorScale } from '../color-formatters.js'
+import { pathParams } from '../index.js'
 import ScrutinizerBase from './scrutinizer-base.js'

 const schema = Joi.object({
@@ -58,19 +59,39 @@ class ScrutinizerQuality extends ScrutinizerQualityBase {
    pattern: ':vcs(g|b)/:user/:repo/:branch*',
  }

-  static examples = [
-    {
-      title: 'Scrutinizer code quality (GitHub/Bitbucket)',
-      pattern: ':vcs(g|b)/:user/:repo/:branch?',
-      namedParams: {
-        vcs: 'g',
-        user: 'filp',
-        repo: 'whoops',
-        branch: 'master',
+  static openApi = {
+    '/scrutinizer/quality/{vcs}/{user}/{repo}': {
+      get: {
+        summary: 'Scrutinizer quality (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({ score: 8.26 }),
    },
-  ]
+    '/scrutinizer/quality/{vcs}/{user}/{repo}/{branch}': {
+      get: {
+        summary: 'Scrutinizer quality (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({
@@ -91,19 +112,29 @@ class ScrutinizerQualityGitLab extends ScrutinizerQualityBase {
  // 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/quality/gl/{instance}/{user}/{repo}': {
+      get: {
+        summary: 'Scrutinizer quality (GitLab)',
+        parameters: pathParams(
+          { name: 'instance', example: 'propertywindow' },
+          { name: 'user', example: 'propertywindow' },
+          { name: 'repo', example: 'client' },
+        ),
      },
-      staticPreview: this.render({ score: 10.0 }),
    },
-  ]
+    '/scrutinizer/quality/gl/{instance}/{user}/{repo}/{branch}': {
+      get: {
+        summary: 'Scrutinizer quality (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({
--- a/services/sourceforge/sourceforge-downloads.service.js
+++ b/services/sourceforge/sourceforge-downloads.service.js
@@ -2,7 +2,7 @@ import Joi from 'joi'
 import dayjs from 'dayjs'
 import { renderDownloadsBadge } from '../downloads.js'
 import { nonNegativeInteger } from '../validators.js'
-import { BaseJsonService } from '../index.js'
+import { BaseJsonService, pathParams } from '../index.js'

 const schema = Joi.object({
  total: nonNegativeInteger,
@@ -32,36 +32,40 @@ export default class SourceforgeDownloads extends BaseJsonService {

  static route = {
    base: 'sourceforge',
-    pattern: ':interval(dt|dm|dw|dd)/:project/:folder*',
+    pattern: ':interval(dd|dw|dm|dt)/:project/:folder*',
  }

-  static examples = [
-    {
-      title: 'SourceForge Downloads',
-      pattern: ':interval(dt|dm|dw|dd)/:project',
-      namedParams: {
-        interval: 'dm',
-        project: 'sevenzip',
+  static openApi = {
+    '/sourceforge/{interval}/{project}': {
+      get: {
+        summary: 'SourceForge Downloads',
+        parameters: pathParams(
+          {
+            name: 'interval',
+            example: 'dm',
+            description: 'Daily, Weekly, Monthly, or Total downloads',
+            schema: { type: 'string', enum: this.getEnum('interval') },
+          },
+          { name: 'project', example: 'sevenzip' },
+        ),
      },
-      staticPreview: this.render({
-        downloads: 215990,
-        interval: 'dm',
-      }),
    },
-    {
-      title: 'SourceForge Downloads (folder)',
-      pattern: ':interval(dt|dm|dw|dd)/:project/:folder',
-      namedParams: {
-        interval: 'dm',
-        project: 'arianne',
-        folder: 'stendhal',
+    '/sourceforge/{interval}/{project}/{folder}': {
+      get: {
+        summary: 'SourceForge Downloads (folder)',
+        parameters: pathParams(
+          {
+            name: 'interval',
+            example: 'dm',
+            description: 'Daily, Weekly, Monthly, or Total downloads',
+            schema: { type: 'string', enum: this.getEnum('interval') },
+          },
+          { name: 'project', example: 'arianne' },
+          { name: 'folder', example: 'stendhal' },
+        ),
      },
-      staticPreview: this.render({
-        downloads: 550,
-        interval: 'dm',
-      }),
    },
-  ]
+  }

  static defaultBadgeData = { label: 'sourceforge' }