migrate examples to openApi part 15; affects [pingpong polymart spiget] (#9561)

* migrate some services from examples to openApi

also move common pingpong bits into a base class

* improve descriptions

services/pingpong/pingpong-base.js

@@ -0,0 +1,22 @@
+import { BaseJsonService, InvalidParameter } from '../index.js'
+
+export const description = `
+[PingPong](https://pingpong.one/) is a status page and monitoring service.
+
+To see more details about this badge and obtain your api key, visit
+[https://my.pingpong.one/integrations/badge-status/](https://my.pingpong.one/integrations/badge-status/)
+`
+
+export const baseUrl = 'https://api.pingpong.one/widget/shields'
+
+export class BasePingPongService extends BaseJsonService {
+  static category = 'monitoring'
+
+  static validateApiKey({ apiKey }) {
+    if (!apiKey.startsWith('sp_')) {
+      throw new InvalidParameter({
+        prettyMessage: 'invalid api key',
+      })
+    }
+  }
+}

services/pingpong/pingpong-status.service.js

@@ -1,39 +1,29 @@
 import Joi from 'joi'
-import { BaseJsonService, InvalidParameter, InvalidResponse } from '../index.js'
+import { InvalidResponse, pathParams } from '../index.js'
+import { BasePingPongService, baseUrl, description } from './pingpong-base.js'
 
 const schema = Joi.object({
   status: Joi.string().required(),
 }).required()
 
-const pingpongDocumentation = `
-To see more details about this badge and obtain your api key, visit
-[https://my.pingpong.one/integrations/badge-status/](https://my.pingpong.one/integrations/badge-status/)
-`
-
-export default class PingPongStatus extends BaseJsonService {
-  static category = 'monitoring'
+export default class PingPongStatus extends BasePingPongService {
   static route = { base: 'pingpong/status', pattern: ':apiKey' }
 
-  static examples = [
-    {
-      title: 'PingPong status',
-      namedParams: { apiKey: 'sp_2e80bc00b6054faeb2b87e2464be337e' },
-      staticPreview: this.render({ status: 'Operational' }),
-      documentation: pingpongDocumentation,
-      keywords: ['statuspage', 'status page'],
+  static openApi = {
+    '/pingpong/status/{apiKey}': {
+      get: {
+        summary: 'PingPong status',
+        description,
+        parameters: pathParams({
+          name: 'apiKey',
+          example: 'sp_2e80bc00b6054faeb2b87e2464be337e',
+        }),
+      },
     },
-  ]
+  }
 
   static defaultBadgeData = { label: 'status' }
 
-  static validateApiKey({ apiKey }) {
-    if (!apiKey.startsWith('sp_')) {
-      throw new InvalidParameter({
-        prettyMessage: 'invalid api key',
-      })
-    }
-  }
-
   static render({ status }) {
     switch (status) {
       case 'Operational':
@@ -54,13 +44,13 @@ export default class PingPongStatus extends BaseJsonService {
   async fetch({ apiKey }) {
     return this._requestJson({
       schema,
-      url: `https://api.pingpong.one/widget/shields/status/${apiKey}`,
+      url: `${baseUrl}/status/${apiKey}`,
     })
   }
 
   async handle({ apiKey }) {
     this.constructor.validateApiKey({ apiKey })
-    const { status } = await this.fetch({ apiKey })
+    const { status } = await this.fetch({ apiKey, schema })
     return this.constructor.render({ status })
   }
 }

services/pingpong/pingpong-uptime.service.js

@@ -1,40 +1,30 @@
 import Joi from 'joi'
 import { coveragePercentage } from '../color-formatters.js'
-import { BaseJsonService, InvalidParameter } from '../index.js'
+import { pathParams } from '../index.js'
+import { BasePingPongService, baseUrl, description } from './pingpong-base.js'
 
 const schema = Joi.object({
   uptime: Joi.number().min(0).max(100).required(),
 }).required()
 
-const pingpongDocumentation = `
-To see more details about this badge and obtain your api key, visit
-[https://my.pingpong.one/integrations/badge-status/](https://my.pingpong.one/integrations/badge-status/)
-`
-
-export default class PingPongUptime extends BaseJsonService {
-  static category = 'monitoring'
+export default class PingPongUptime extends BasePingPongService {
   static route = { base: 'pingpong/uptime', pattern: ':apiKey' }
 
-  static examples = [
-    {
-      title: 'PingPong uptime (last 30 days)',
-      namedParams: { apiKey: 'sp_2e80bc00b6054faeb2b87e2464be337e' },
-      staticPreview: this.render({ uptime: 100 }),
-      documentation: pingpongDocumentation,
-      keywords: ['statuspage', 'status page'],
+  static openApi = {
+    '/pingpong/uptime/{apiKey}': {
+      get: {
+        summary: 'PingPong uptime (last 30 days)',
+        description,
+        parameters: pathParams({
+          name: 'apiKey',
+          example: 'sp_2e80bc00b6054faeb2b87e2464be337e',
+        }),
+      },
     },
-  ]
+  }
 
   static defaultBadgeData = { label: 'uptime' }
 
-  static validateApiKey({ apiKey }) {
-    if (!apiKey.startsWith('sp_')) {
-      throw new InvalidParameter({
-        prettyMessage: 'invalid api key',
-      })
-    }
-  }
-
   static render({ uptime }) {
     return {
       message: `${uptime}%`,
@@ -45,13 +35,13 @@ export default class PingPongUptime extends BaseJsonService {
   async fetch({ apiKey }) {
     return this._requestJson({
       schema,
-      url: `https://api.pingpong.one/widget/shields/uptime/${apiKey}`,
+      url: `${baseUrl}/uptime/${apiKey}`,
     })
   }
 
   async handle({ apiKey }) {
     this.constructor.validateApiKey({ apiKey })
-    const { uptime } = await this.fetch({ apiKey })
+    const { uptime } = await this.fetch({ apiKey, schema })
     return this.constructor.render({ uptime })
   }
 }

services/polymart/polymart-base.js

@@ -31,7 +31,7 @@ const resourceFoundOrNotSchema = Joi.alternatives(
   notFoundResourceSchema,
 )
 
-const documentation = `
+const description = `
 <p>You can find your resource ID in the url for your resource page.</p>
 <p>Example: <code>https://polymart.org/resource/polymart-plugin.323</code> - Here the Resource ID is 323.</p>`
 
@@ -48,4 +48,4 @@ class BasePolymartService extends BaseJsonService {
   }
 }
 
-export { documentation, BasePolymartService }
+export { description, BasePolymartService }

services/polymart/polymart-downloads.service.js

@@ -1,6 +1,7 @@
+import { pathParams } from '../index.js'
 import { NotFound } from '../../core/base-service/errors.js'
 import { renderDownloadsBadge } from '../downloads.js'
-import { BasePolymartService, documentation } from './polymart-base.js'
+import { BasePolymartService, description } from './polymart-base.js'
 
 export default class PolymartDownloads extends BasePolymartService {
   static category = 'downloads'
@@ -10,16 +11,18 @@ export default class PolymartDownloads extends BasePolymartService {
     pattern: ':resourceId',
   }
 
-  static examples = [
-    {
-      title: 'Polymart Downloads',
-      namedParams: {
-        resourceId: '323',
+  static openApi = {
+    '/polymart/downloads/{resourceId}': {
+      get: {
+        summary: 'Polymart Downloads',
+        description,
+        parameters: pathParams({
+          name: 'resourceId',
+          example: '323',
+        }),
       },
-      staticPreview: renderDownloadsBadge({ downloads: 655 }),
-      documentation,
     },
-  ]
+  }
 
   static defaultBadgeData = {
     label: 'downloads',

services/polymart/polymart-latest-version.service.js

@@ -1,6 +1,8 @@
+import { pathParams } from '../index.js'
 import { NotFound } from '../../core/base-service/errors.js'
 import { renderVersionBadge } from '../version.js'
-import { BasePolymartService, documentation } from './polymart-base.js'
+import { BasePolymartService, description } from './polymart-base.js'
+
 export default class PolymartLatestVersion extends BasePolymartService {
   static category = 'version'
 
@@ -9,18 +11,18 @@ export default class PolymartLatestVersion extends BasePolymartService {
     pattern: ':resourceId',
   }
 
-  static examples = [
-    {
-      title: 'Polymart Version',
-      namedParams: {
-        resourceId: '323',
+  static openApi = {
+    '/polymart/version/{resourceId}': {
+      get: {
+        summary: 'Polymart Version',
+        description,
+        parameters: pathParams({
+          name: 'resourceId',
+          example: '323',
+        }),
       },
-      staticPreview: renderVersionBadge({
-        version: 'v1.2.9',
-      }),
-      documentation,
     },
-  ]
+  }
 
   static defaultBadgeData = {
     label: 'polymart',

services/polymart/polymart-rating.service.js

@@ -1,7 +1,8 @@
+import { pathParams } from '../index.js'
 import { starRating, metric } from '../text-formatters.js'
 import { floorCount } from '../color-formatters.js'
 import { NotFound } from '../../core/base-service/errors.js'
-import { BasePolymartService, documentation } from './polymart-base.js'
+import { BasePolymartService, description } from './polymart-base.js'
 
 export default class PolymartRatings extends BasePolymartService {
   static category = 'rating'
@@ -11,30 +12,25 @@ export default class PolymartRatings extends BasePolymartService {
     pattern: ':format(rating|stars)/:resourceId',
   }
 
-  static examples = [
-    {
-      title: 'Polymart Stars',
-      pattern: 'stars/:resourceId',
-      namedParams: {
-        resourceId: '323',
+  static openApi = {
+    '/polymart/{format}/{resourceId}': {
+      get: {
+        summary: 'Polymart Rating',
+        description,
+        parameters: pathParams(
+          {
+            name: 'format',
+            example: 'rating',
+            schema: { type: 'string', enum: this.getEnum('format') },
+          },
+          {
+            name: 'resourceId',
+            example: '323',
+          },
+        ),
       },
-      staticPreview: this.render({
-        format: 'stars',
-        total: 14,
-        average: 5,
-      }),
-      documentation,
     },
-    {
-      title: 'Polymart Rating',
-      pattern: 'rating/:resourceId',
-      namedParams: {
-        resourceId: '323',
-      },
-      staticPreview: this.render({ total: 14, average: 5 }),
-      documentation,
-    },
-  ]
+  }
 
   static defaultBadgeData = {
     label: 'rating',

services/spiget/spiget-base.js

@@ -15,12 +15,11 @@ const resourceSchema = Joi.object({
   }).required(),
 }).required()
 
-const documentation = `
+const description = `
+<p><a href="https://spiget.org/">Spiget</a> holds information about SpigotMC Resources, Plugins and Authors.</p>
 <p>You can find your resource ID in the url for your resource page.</p>
 <p>Example: <code>https://www.spigotmc.org/resources/essentialsx.9089/</code> - Here the Resource ID is 9089.</p>`
 
-const keywords = ['spigot', 'spigotmc']
-
 class BaseSpigetService extends BaseJsonService {
   async fetch({
     resourceId,
@@ -34,4 +33,4 @@ class BaseSpigetService extends BaseJsonService {
   }
 }
 
-export { keywords, documentation, BaseSpigetService }
+export { description, BaseSpigetService }

services/spiget/spiget-download-size.service.js

@@ -1,4 +1,5 @@
-import { BaseSpigetService, documentation, keywords } from './spiget-base.js'
+import { pathParams } from '../index.js'
+import { BaseSpigetService, description } from './spiget-base.js'
 
 export default class SpigetDownloadSize extends BaseSpigetService {
   static category = 'size'
@@ -8,15 +9,18 @@ export default class SpigetDownloadSize extends BaseSpigetService {
     pattern: ':resourceId',
   }
 
-  static examples = [
-    {
-      title: 'Spiget Download Size',
-      namedParams: { resourceId: '15904' },
-      staticPreview: this.render({ size: 2.5, unit: 'MB' }),
-      documentation,
-      keywords,
+  static openApi = {
+    '/spiget/download-size/{resourceId}': {
+      get: {
+        summary: 'Spiget Download Size',
+        description,
+        parameters: pathParams({
+          name: 'resourceId',
+          example: '15904',
+        }),
+      },
     },
-  ]
+  }
 
   static defaultBadgeData = {
     label: 'size',

services/spiget/spiget-downloads.service.js

@@ -1,5 +1,6 @@
+import { pathParams } from '../index.js'
 import { renderDownloadsBadge } from '../downloads.js'
-import { BaseSpigetService, documentation, keywords } from './spiget-base.js'
+import { BaseSpigetService, description } from './spiget-base.js'
 
 export default class SpigetDownloads extends BaseSpigetService {
   static category = 'downloads'
@@ -9,17 +10,18 @@ export default class SpigetDownloads extends BaseSpigetService {
     pattern: ':resourceId',
   }
 
-  static examples = [
-    {
-      title: 'Spiget Downloads',
-      namedParams: {
-        resourceId: '9089',
+  static openApi = {
+    '/spiget/downloads/{resourceId}': {
+      get: {
+        summary: 'Spiget Downloads',
+        description,
+        parameters: pathParams({
+          name: 'resourceId',
+          example: '9089',
+        }),
       },
-      staticPreview: renderDownloadsBadge({ downloads: 560891 }),
-      documentation,
-      keywords,
     },
-  ]
+  }
 
   static defaultBadgeData = { label: 'downloads' }
 

services/spiget/spiget-latest-version.service.js

@@ -1,6 +1,7 @@
 import Joi from 'joi'
+import { pathParams } from '../index.js'
 import { renderVersionBadge } from '../version.js'
-import { BaseSpigetService, documentation, keywords } from './spiget-base.js'
+import { BaseSpigetService, description } from './spiget-base.js'
 
 const versionSchema = Joi.object({
   downloads: Joi.number().required(),
@@ -15,17 +16,18 @@ export default class SpigetLatestVersion extends BaseSpigetService {
     pattern: ':resourceId',
   }
 
-  static examples = [
-    {
-      title: 'Spiget Version',
-      namedParams: {
-        resourceId: '9089',
+  static openApi = {
+    '/spiget/version/{resourceId}': {
+      get: {
+        summary: 'Spiget Version',
+        description,
+        parameters: pathParams({
+          name: 'resourceId',
+          example: '9089',
+        }),
       },
-      staticPreview: renderVersionBadge({ version: 2.1 }),
-      documentation,
-      keywords,
     },
-  ]
+  }
 
   static defaultBadgeData = {
     label: 'spiget',

services/spiget/spiget-rating.service.js

@@ -1,6 +1,7 @@
+import { pathParams } from '../index.js'
 import { starRating, metric } from '../text-formatters.js'
 import { floorCount } from '../color-formatters.js'
-import { BaseSpigetService, documentation, keywords } from './spiget-base.js'
+import { BaseSpigetService, description } from './spiget-base.js'
 
 export default class SpigetRatings extends BaseSpigetService {
   static category = 'rating'
@@ -10,31 +11,25 @@ export default class SpigetRatings extends BaseSpigetService {
     pattern: ':format(rating|stars)/:resourceId',
   }
 
-  static examples = [
-    {
-      title: 'Spiget Stars',
-      pattern: 'stars/:resourceId',
-      namedParams: {
-        resourceId: '9089',
+  static openApi = {
+    '/spiget/{format}/{resourceId}': {
+      get: {
+        summary: 'Spiget Rating',
+        description,
+        parameters: pathParams(
+          {
+            name: 'format',
+            example: 'rating',
+            schema: { type: 'string', enum: this.getEnum('format') },
+          },
+          {
+            name: 'resourceId',
+            example: '9089',
+          },
+        ),
       },
-      staticPreview: this.render({
-        format: 'stars',
-        total: 325,
-        average: 4.5,
-      }),
-      documentation,
     },
-    {
-      title: 'Spiget Rating',
-      pattern: 'rating/:resourceId',
-      namedParams: {
-        resourceId: '9089',
-      },
-      staticPreview: this.render({ total: 325, average: 4.5 }),
-      documentation,
-      keywords,
-    },
-  ]
+  }
 
   static defaultBadgeData = {
     label: 'rating',

services/spiget/spiget-tested-versions.service.js

@@ -1,4 +1,5 @@
-import { BaseSpigetService, documentation, keywords } from './spiget-base.js'
+import { pathParams } from '../index.js'
+import { BaseSpigetService, description } from './spiget-base.js'
 
 export default class SpigetTestedVersions extends BaseSpigetService {
   static category = 'platform-support'
@@ -8,17 +9,18 @@ export default class SpigetTestedVersions extends BaseSpigetService {
     pattern: ':resourceId',
   }
 
-  static examples = [
-    {
-      title: 'Spiget tested server versions',
-      namedParams: {
-        resourceId: '9089',
+  static openApi = {
+    '/spiget/tested-versions/{resourceId}': {
+      get: {
+        summary: 'Spiget tested server versions',
+        description,
+        parameters: pathParams({
+          name: 'resourceId',
+          example: '9089',
+        }),
       },
-      staticPreview: this.render({ versions: '1.7-1.13' }),
-      documentation,
-      keywords,
     },
-  ]
+  }
 
   static defaultBadgeData = {
     label: 'tested versions',