migrate some services from examples to openApi (#9841)

services/bstats/bstats-players.service.js

@@ -1,6 +1,6 @@
 import Joi from 'joi'
 import { metric } from '../text-formatters.js'
-import { BaseJsonService } from '../index.js'
+import { BaseJsonService, pathParams } from '../index.js'
 
 const schema = Joi.array()
   .items(Joi.array().items(Joi.number().required(), Joi.number().required()))
@@ -10,15 +10,17 @@ export default class BStatsPlayers extends BaseJsonService {
   static category = 'other'
   static route = { base: 'bstats/players', pattern: ':pluginid' }
 
-  static examples = [
-    {
-      title: 'bStats Players',
-      namedParams: {
-        pluginid: '1',
+  static openApi = {
+    '/bstats/players/{pluginid}': {
+      get: {
+        summary: 'bStats Players',
+        parameters: pathParams({
+          name: 'pluginid',
+          example: '1',
+        }),
       },
-      staticPreview: this.render({ players: 74299 }),
     },
-  ]
+  }
 
   static defaultBadgeData = { label: 'players', color: 'blue' }
 

services/bstats/bstats-servers.service.js

@@ -1,6 +1,6 @@
 import Joi from 'joi'
 import { metric } from '../text-formatters.js'
-import { BaseJsonService } from '../index.js'
+import { BaseJsonService, pathParams } from '../index.js'
 
 const schema = Joi.array()
   .items(Joi.array().items(Joi.number().required(), Joi.number().required()))
@@ -10,15 +10,17 @@ export default class BStatsServers extends BaseJsonService {
   static category = 'other'
   static route = { base: 'bstats/servers', pattern: ':pluginid' }
 
-  static examples = [
-    {
-      title: 'bStats Servers',
-      namedParams: {
-        pluginid: '1',
+  static openApi = {
+    '/bstats/servers/{pluginid}': {
+      get: {
+        summary: 'bStats Servers',
+        parameters: pathParams({
+          name: 'pluginid',
+          example: '1',
+        }),
       },
-      staticPreview: this.render({ servers: 57479 }),
     },
-  ]
+  }
 
   static defaultBadgeData = { label: 'servers', color: 'blue' }
 

services/bugzilla/bugzilla.service.js

@@ -1,6 +1,6 @@
 import Joi from 'joi'
 import { optionalUrl } from '../validators.js'
-import { BaseJsonService } from '../index.js'
+import { BaseJsonService, pathParam, queryParam } from '../index.js'
 
 const queryParamSchema = Joi.object({
   baseUrl: optionalUrl,
@@ -18,8 +18,9 @@ const schema = Joi.object({
     .required(),
 }).required()
 
-const documentation = `
+const description = `
 <p>
+  Use the <code>baseUrl</code> query parameter to target different Bugzilla deployments.
   If your Bugzilla badge errors, it might be because you are trying to load a private bug.
 </p>
 `
@@ -28,33 +29,26 @@ export default class Bugzilla extends BaseJsonService {
   static category = 'issue-tracking'
   static route = { base: 'bugzilla', pattern: ':bugNumber', queryParamSchema }
 
-  static examples = [
-    {
-      title: 'Bugzilla bug status (Mozilla)',
-      namedParams: {
-        bugNumber: '996038',
+  static openApi = {
+    '/bugzilla/{bugNumber}': {
+      get: {
+        summary: 'Bugzilla bug status',
+        description,
+        parameters: [
+          pathParam({
+            name: 'bugNumber',
+            example: '545424',
+          }),
+          queryParam({
+            name: 'baseUrl',
+            example: 'https://bugs.eclipse.org/bugs',
+            description:
+              'When not specified, this will default to `https://bugzilla.mozilla.org`.',
+          }),
+        ],
       },
-      staticPreview: this.render({
-        bugNumber: 996038,
-        status: 'FIXED',
-        resolution: '',
-      }),
-      documentation,
     },
-    {
-      title: 'Bugzilla bug status (non-Mozilla)',
-      namedParams: {
-        bugNumber: '545424',
-      },
-      queryParams: { baseUrl: 'https://bugs.eclipse.org/bugs' },
-      staticPreview: this.render({
-        bugNumber: 545424,
-        status: 'RESOLVED',
-        resolution: 'FIXED',
-      }),
-      documentation,
-    },
-  ]
+  }
 
   static defaultBadgeData = { label: 'bugzilla' }
 

services/eclipse-marketplace/eclipse-marketplace-base.js

@@ -1,13 +1,6 @@
 import { BaseXmlService } from '../index.js'
 
 export default class EclipseMarketplaceBase extends BaseXmlService {
-  static buildRoute(base) {
-    return {
-      base,
-      pattern: ':name',
-    }
-  }
-
   async fetch({ name, schema }) {
     return this._requestXml({
       schema,

services/eclipse-marketplace/eclipse-marketplace-downloads.service.js

@@ -1,69 +1,58 @@
 import Joi from 'joi'
 import { renderDownloadsBadge } from '../downloads.js'
+import { pathParams } from '../index.js'
 import { nonNegativeInteger } from '../validators.js'
 import EclipseMarketplaceBase from './eclipse-marketplace-base.js'
 
-const monthlyResponseSchema = Joi.object({
+const downloadsResponseSchema = Joi.object({
   marketplace: Joi.object({
     node: Joi.object({
       installsrecent: nonNegativeInteger,
-    }),
-  }),
-}).required()
-
-const totalResponseSchema = Joi.object({
-  marketplace: Joi.object({
-    node: Joi.object({
       installstotal: nonNegativeInteger,
     }),
   }),
 }).required()
 
-function DownloadsForInterval(downloadsInterval) {
-  const {
-    base,
-    schema,
-    interval = '',
-    name,
-  } = {
-    month: {
-      base: 'eclipse-marketplace/dm',
-      interval: 'month',
-      schema: monthlyResponseSchema,
-      name: 'EclipseMarketplaceDownloadsMonth',
-    },
-    total: {
-      base: 'eclipse-marketplace/dt',
-      schema: totalResponseSchema,
-      name: 'EclipseMarketplaceDownloadsTotal',
-    },
-  }[downloadsInterval]
+export default class EclipseMarketplaceDownloads extends EclipseMarketplaceBase {
+  static category = 'downloads'
+  static route = {
+    base: 'eclipse-marketplace',
+    pattern: ':interval(dm|dt)/:name',
+  }
 
-  return class EclipseMarketplaceDownloads extends EclipseMarketplaceBase {
-    static name = name
-    static category = 'downloads'
-    static route = this.buildRoute(base)
-    static examples = [
-      {
-        title: 'Eclipse Marketplace',
-        namedParams: { name: 'notepad4e' },
-        staticPreview: this.render({ downloads: 30000 }),
+  static openApi = {
+    '/eclipse-marketplace/{interval}/{name}': {
+      get: {
+        summary: 'Eclipse Marketplace Downloads',
+        parameters: pathParams(
+          {
+            name: 'interval',
+            example: 'dt',
+            schema: { type: 'string', enum: this.getEnum('interval') },
+          },
+          {
+            name: 'name',
+            example: 'planet-themes',
+          },
+        ),
       },
-    ]
+    },
+  }
 
-    static render({ downloads }) {
-      return renderDownloadsBadge({ downloads, interval })
-    }
+  static render({ interval, downloads }) {
+    const intervalString = interval === 'dm' ? 'month' : null
+    return renderDownloadsBadge({ downloads, interval: intervalString })
+  }
 
-    async handle({ name }) {
-      const { marketplace } = await this.fetch({ name, schema })
-      const downloads =
-        downloadsInterval === 'total'
-          ? marketplace.node.installstotal
-          : marketplace.node.installsrecent
-      return this.constructor.render({ downloads })
-    }
+  async handle({ interval, name }) {
+    const { marketplace } = await this.fetch({
+      schema: downloadsResponseSchema,
+      name,
+    })
+    const downloads =
+      interval === 'dt'
+        ? marketplace.node.installstotal
+        : marketplace.node.installsrecent
+    return this.constructor.render({ downloads, interval })
   }
 }
-
-export default ['month', 'total'].map(DownloadsForInterval)

services/eclipse-marketplace/eclipse-marketplace-favorites.service.js

@@ -13,7 +13,11 @@ const favoritesResponseSchema = Joi.object({
 
 export default class EclipseMarketplaceFavorites extends EclipseMarketplaceBase {
   static category = 'other'
-  static route = this.buildRoute('eclipse-marketplace/favorites')
+  static route = {
+    base: 'eclipse-marketplace/favorites',
+    pattern: ':name',
+  }
+
   static openApi = {
     '/eclipse-marketplace/favorites/{name}': {
       get: {

services/eclipse-marketplace/eclipse-marketplace-license.service.js

@@ -12,7 +12,11 @@ const licenseResponseSchema = Joi.object({
 
 export default class EclipseMarketplaceLicense extends EclipseMarketplaceBase {
   static category = 'license'
-  static route = this.buildRoute('eclipse-marketplace/l')
+  static route = {
+    base: 'eclipse-marketplace/l',
+    pattern: ':name',
+  }
+
   static openApi = {
     '/eclipse-marketplace/l/{name}': {
       get: {

services/eclipse-marketplace/eclipse-marketplace-update.service.js

@@ -15,7 +15,11 @@ const updateResponseSchema = Joi.object({
 
 export default class EclipseMarketplaceUpdate extends EclipseMarketplaceBase {
   static category = 'activity'
-  static route = this.buildRoute('eclipse-marketplace/last-update')
+  static route = {
+    base: 'eclipse-marketplace/last-update',
+    pattern: ':name',
+  }
+
   static openApi = {
     '/eclipse-marketplace/last-update/{name}': {
       get: {

services/eclipse-marketplace/eclipse-marketplace-version.service.js

@@ -13,7 +13,11 @@ const versionResponseSchema = Joi.object({
 
 export default class EclipseMarketplaceVersion extends EclipseMarketplaceBase {
   static category = 'version'
-  static route = this.buildRoute('eclipse-marketplace/v')
+  static route = {
+    base: 'eclipse-marketplace/v',
+    pattern: ':name',
+  }
+
   static openApi = {
     '/eclipse-marketplace/v/{name}': {
       get: {