migrate some services from examples to openApi (#9749)

services/ctan/ctan.service.js

@@ -1,7 +1,7 @@
 import Joi from 'joi'
 import { renderLicenseBadge } from '../licenses.js'
 import { renderVersionBadge } from '../version.js'
-import { BaseJsonService, InvalidResponse } from '../index.js'
+import { BaseJsonService, InvalidResponse, pathParams } from '../index.js'
 
 const schema = Joi.object({
   license: Joi.array().items(Joi.string()).single(),
@@ -11,6 +11,8 @@ const schema = Joi.object({
   }).required(),
 }).required()
 
+const description = '[CTAN](https://ctan.org/) is a package registry for TeX.'
+
 class BaseCtanService extends BaseJsonService {
   static defaultBadgeData = { label: 'ctan' }
 
@@ -27,14 +29,18 @@ class CtanLicense extends BaseCtanService {
   static category = 'license'
   static route = { base: 'ctan/l', pattern: ':library' }
 
-  static examples = [
-    {
-      title: 'CTAN',
-      namedParams: { library: 'novel' },
-      staticPreview: this.render({ licenses: ['ppl1.3c', 'ofl'] }),
-      keywords: ['tex'],
+  static openApi = {
+    '/ctan/l/{library}': {
+      get: {
+        summary: 'CTAN License',
+        description,
+        parameters: pathParams({
+          name: 'library',
+          example: 'novel',
+        }),
+      },
     },
-  ]
+  }
 
   static defaultBadgeData = { label: 'license' }
 
@@ -53,14 +59,18 @@ class CtanVersion extends BaseCtanService {
   static category = 'version'
   static route = { base: 'ctan/v', pattern: ':library' }
 
-  static examples = [
-    {
-      title: 'CTAN',
-      namedParams: { library: 'tex' },
-      staticPreview: this.render({ version: '3.14159265' }),
-      keywords: ['tex'],
+  static openApi = {
+    '/ctan/v/{library}': {
+      get: {
+        summary: 'CTAN Version',
+        description,
+        parameters: pathParams({
+          name: 'library',
+          example: 'tex',
+        }),
+      },
     },
-  ]
+  }
 
   static render({ version }) {
     return renderVersionBadge({ version })

services/dub/dub-download.service.js

@@ -1,7 +1,7 @@
 import Joi from 'joi'
 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({
   downloads: Joi.object({
@@ -38,39 +38,46 @@ export default class DubDownloads extends BaseJsonService {
     pattern: ':interval(dd|dw|dm|dt)/:packageName/:version*',
   }
 
-  static examples = [
-    {
-      title: 'DUB',
-      namedParams: { interval: 'dm', packageName: 'vibe-d' },
-      staticPreview: this.render({ interval: 'dm', downloads: 5000 }),
-    },
-    {
-      title: 'DUB (version)',
-      namedParams: {
-        interval: 'dm',
-        packageName: 'vibe-d',
-        version: '0.8.4',
+  static openApi = {
+    '/dub/{interval}/{packageName}': {
+      get: {
+        summary: 'DUB Downloads',
+        parameters: pathParams(
+          {
+            name: 'interval',
+            example: 'dm',
+            schema: { type: 'string', enum: this.getEnum('interval') },
+          },
+          {
+            name: 'packageName',
+            example: 'vibe-d',
+          },
+        ),
       },
-      staticPreview: this.render({
-        interval: 'dm',
-        version: '0.8.4',
-        downloads: 100,
-      }),
     },
-    {
-      title: 'DUB (latest)',
-      namedParams: {
-        interval: 'dm',
-        packageName: 'vibe-d',
-        version: 'latest',
+    '/dub/{interval}/{packageName}/{version}': {
+      get: {
+        summary: 'DUB Downloads (specific version)',
+        parameters: pathParams(
+          {
+            name: 'interval',
+            example: 'dm',
+            schema: { type: 'string', enum: this.getEnum('interval') },
+          },
+          {
+            name: 'packageName',
+            example: 'vibe-d',
+          },
+          {
+            name: 'version',
+            description:
+              'This can either be a numeric version like `0.8.4` or the string `latest`',
+            example: '0.8.4',
+          },
+        ),
       },
-      staticPreview: this.render({
-        interval: 'dm',
-        version: 'latest',
-        downloads: 100,
-      }),
     },
-  ]
+  }
 
   static defaultBadgeData = { label: 'downloads' }
 

services/dub/dub-score.service.js

@@ -1,5 +1,5 @@
 import Joi from 'joi'
-import { BaseJsonService } from '../index.js'
+import { BaseJsonService, pathParams } from '../index.js'
 import { colorScale } from '../color-formatters.js'
 
 const schema = Joi.object({
@@ -11,13 +11,17 @@ export default class DubScore extends BaseJsonService {
 
   static route = { base: 'dub/score', pattern: ':packageName' }
 
-  static examples = [
-    {
-      title: 'DUB Score',
-      namedParams: { packageName: 'vibe-d' },
-      staticPreview: this.render({ score: 4.5 }),
+  static openApi = {
+    '/dub/score/{packageName}': {
+      get: {
+        summary: 'DUB Score',
+        parameters: pathParams({
+          name: 'packageName',
+          example: 'vibe-d',
+        }),
+      },
     },
-  ]
+  }
 
   static defaultBadgeData = { label: 'score' }
 

services/hexpm/hexpm.service.js

@@ -2,7 +2,7 @@ import Joi from 'joi'
 import { renderDownloadsBadge } from '../downloads.js'
 import { maybePluralize } from '../text-formatters.js'
 import { renderVersionBadge } from '../version.js'
-import { BaseJsonService } from '../index.js'
+import { BaseJsonService, pathParams } from '../index.js'
 
 const hexSchema = Joi.object({
   downloads: Joi.object({
@@ -18,6 +18,8 @@ const hexSchema = Joi.object({
   latest_version: Joi.string().required(),
 }).required()
 
+const description = '[Hex.pm](https://hex.pm/) is a package registry for Erlang'
+
 class BaseHexPmService extends BaseJsonService {
   static defaultBadgeData = { label: 'hex' }
 
@@ -37,13 +39,18 @@ class HexPmLicense extends BaseHexPmService {
     pattern: ':packageName',
   }
 
-  static examples = [
-    {
-      title: 'Hex.pm',
-      namedParams: { packageName: 'plug' },
-      staticPreview: this.render({ licenses: ['Apache 2'] }),
+  static openApi = {
+    '/hexpm/l/{packageName}': {
+      get: {
+        summary: 'Hex.pm License',
+        description,
+        parameters: pathParams({
+          name: 'packageName',
+          example: 'plug',
+        }),
+      },
     },
-  ]
+  }
 
   static defaultBadgeData = { label: 'license' }
 
@@ -76,13 +83,18 @@ class HexPmVersion extends BaseHexPmService {
     pattern: ':packageName',
   }
 
-  static examples = [
-    {
-      title: 'Hex.pm',
-      namedParams: { packageName: 'plug' },
-      staticPreview: this.render({ version: '1.6.4' }),
+  static openApi = {
+    '/hexpm/v/{packageName}': {
+      get: {
+        summary: 'Hex.pm Version',
+        description,
+        parameters: pathParams({
+          name: 'packageName',
+          example: 'plug',
+        }),
+      },
     },
-  ]
+  }
 
   static render({ version }) {
     return renderVersionBadge({ version })
@@ -96,52 +108,58 @@ class HexPmVersion extends BaseHexPmService {
   }
 }
 
-function DownloadsForInterval(downloadInterval) {
-  const { base, interval, name } = {
-    day: {
-      base: 'hexpm/dd',
-      interval: 'day',
-      name: 'HexPmDownloadsDay',
-    },
-    week: {
-      base: 'hexpm/dw',
-      interval: 'week',
-      name: 'HexPmDownloadsWeek',
-    },
-    all: {
-      base: 'hexpm/dt',
-      name: 'HexPmDownloadsTotal',
-    },
-  }[downloadInterval]
+const periodMap = {
+  dd: {
+    field: 'day',
+    label: 'day',
+  },
+  dw: {
+    field: 'week',
+    label: 'week',
+  },
+  dt: {
+    field: 'all',
+  },
+}
 
-  return class HexPmDownloads extends BaseHexPmService {
-    static name = name
+class HexPmDownloads extends BaseHexPmService {
+  static category = 'downloads'
 
-    static category = 'downloads'
+  static route = {
+    base: 'hexpm',
+    pattern: ':interval(dd|dw|dt)/:packageName',
+  }
 
-    static route = {
-      base,
-      pattern: ':packageName',
-    }
-
-    static examples = [
-      {
-        title: 'Hex.pm',
-        namedParams: { packageName: 'plug' },
-        staticPreview: renderDownloadsBadge({ downloads: 85000 }),
+  static openApi = {
+    '/hexpm/{interval}/{packageName}': {
+      get: {
+        summary: 'Hex.pm Downloads',
+        description,
+        parameters: pathParams(
+          {
+            name: 'interval',
+            example: 'dw',
+            schema: { type: 'string', enum: this.getEnum('interval') },
+          },
+          {
+            name: 'packageName',
+            example: 'plug',
+          },
+        ),
       },
-    ]
+    },
+  }
 
-    static defaultBadgeData = { label: 'downloads' }
+  static defaultBadgeData = { label: 'downloads' }
 
-    async handle({ packageName }) {
-      const json = await this.fetch({ packageName })
-      const downloads = json.downloads[downloadInterval]
-      return renderDownloadsBadge({ downloads, interval })
-    }
+  async handle({ interval, packageName }) {
+    const json = await this.fetch({ packageName })
+    const downloads = json.downloads[periodMap[interval].field]
+    return renderDownloadsBadge({
+      downloads,
+      interval: periodMap[interval].label,
+    })
   }
 }
 
-const downloadsServices = ['day', 'week', 'all'].map(DownloadsForInterval)
-
-export default [...downloadsServices, HexPmLicense, HexPmVersion]
+export default [HexPmDownloads, HexPmLicense, HexPmVersion]

services/jira/jira-issue.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'
 import { authConfig } from './jira-common.js'
 
 const queryParamSchema = Joi.object({
@@ -29,22 +29,24 @@ export default class JiraIssue extends BaseJsonService {
 
   static auth = authConfig
 
-  static examples = [
-    {
-      title: 'JIRA issue',
-      namedParams: {
-        issueKey: 'KAFKA-2896',
+  static openApi = {
+    '/jira/issue/{issueKey}': {
+      get: {
+        summary: 'JIRA issue',
+        parameters: [
+          pathParam({
+            name: 'issueKey',
+            example: 'KAFKA-2896',
+          }),
+          queryParam({
+            name: 'baseUrl',
+            example: 'https://issues.apache.org/jira',
+            required: true,
+          }),
+        ],
       },
-      queryParams: {
-        baseUrl: 'https://issues.apache.org/jira',
-      },
-      staticPreview: this.render({
-        issueKey: 'KAFKA-2896',
-        statusName: 'Resolved',
-        statusColor: 'green',
-      }),
     },
-  ]
+  }
 
   static defaultBadgeData = { color: 'lightgrey', label: 'jira' }
 

services/jira/jira-sprint.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'
 import { authConfig } from './jira-common.js'
 
 const queryParamSchema = Joi.object({
@@ -22,7 +22,7 @@ const schema = Joi.object({
     .required(),
 }).required()
 
-const documentation = `
+const description = `
 To get the \`Sprint ID\`, go to your Backlog view in your project,
 right click on your sprint name and get the value of
 \`data-sprint-id\`.
@@ -39,22 +39,25 @@ export default class JiraSprint extends BaseJsonService {
 
   static auth = authConfig
 
-  static examples = [
-    {
-      title: 'JIRA sprint completion',
-      namedParams: {
-        sprintId: '94',
+  static openApi = {
+    '/jira/sprint/{sprintId}': {
+      get: {
+        summary: 'JIRA sprint completion',
+        description,
+        parameters: [
+          pathParam({
+            name: 'sprintId',
+            example: '94',
+          }),
+          queryParam({
+            name: 'baseUrl',
+            example: 'https://issues.apache.org/jira',
+            required: true,
+          }),
+        ],
       },
-      queryParams: {
-        baseUrl: 'https://jira.spring.io',
-      },
-      staticPreview: this.render({
-        numCompletedIssues: 27,
-        numTotalIssues: 28,
-      }),
-      documentation,
     },
-  ]
+  }
 
   static defaultBadgeData = { label: 'jira' }
 

services/pulsar/pulsar-downloads.service.js

@@ -1,5 +1,5 @@
 import Joi from 'joi'
-import { BaseJsonService } from '../index.js'
+import { BaseJsonService, pathParams } from '../index.js'
 import { metric } from '../text-formatters.js'
 import { nonNegativeInteger } from '../validators.js'
 import { pulsarPurple } from './pulsar-helper.js'
@@ -13,13 +13,17 @@ export default class PulsarDownloads extends BaseJsonService {
 
   static route = { base: 'pulsar/dt', pattern: ':packageName' }
 
-  static examples = [
-    {
-      title: 'Pulsar Downloads',
-      namedParams: { packageName: 'hey-pane' },
-      staticPreview: this.render({ downloadCount: 1000 }),
+  static openApi = {
+    '/pulsar/dt/{packageName}': {
+      get: {
+        summary: 'Pulsar Downloads',
+        parameters: pathParams({
+          name: 'packageName',
+          example: 'hey-pane',
+        }),
+      },
     },
-  ]
+  }
 
   static defaultBadgeData = { label: 'downloads' }
 

services/pulsar/pulsar-stargazers.service.js

@@ -1,5 +1,5 @@
 import Joi from 'joi'
-import { BaseJsonService } from '../index.js'
+import { BaseJsonService, pathParams } from '../index.js'
 import { metric } from '../text-formatters.js'
 import { nonNegativeInteger } from '../validators.js'
 import { pulsarPurple } from './pulsar-helper.js'
@@ -13,13 +13,17 @@ export default class PulsarStargazers extends BaseJsonService {
 
   static route = { base: 'pulsar/stargazers', pattern: ':packageName' }
 
-  static examples = [
-    {
-      title: 'Pulsar Stargazers',
-      namedParams: { packageName: 'hey-pane' },
-      staticPreview: this.render({ stargazerCount: 1000 }),
+  static openApi = {
+    '/pulsar/stargazers/{packageName}': {
+      get: {
+        summary: 'Pulsar Stargazers',
+        parameters: pathParams({
+          name: 'packageName',
+          example: 'hey-pane',
+        }),
+      },
     },
-  ]
+  }
 
   static defaultBadgeData = { label: 'stargazers' }
 

services/scoop/scoop-version.service.js

@@ -1,5 +1,5 @@
 import Joi from 'joi'
-import { NotFound } from '../index.js'
+import { NotFound, pathParam, queryParam } from '../index.js'
 import { ConditionalGithubAuthV3Service } from '../github/github-auth-service.js'
 import { fetchJsonFromRepo } from '../github/github-common-fetch.js'
 import { renderVersionBadge } from '../version.js'
@@ -29,19 +29,19 @@ export default class ScoopVersion extends ConditionalGithubAuthV3Service {
     queryParamSchema,
   }
 
-  static examples = [
-    {
-      title: 'Scoop Version',
-      namedParams: { app: 'ngrok' },
-      staticPreview: this.render({ version: '2.3.35' }),
+  static openApi = {
+    '/scoop/v/{app}': {
+      get: {
+        summary: 'Scoop Version',
+        description:
+          '[Scoop](https://scoop.sh/) is a command-line installer for Windows',
+        parameters: [
+          pathParam({ name: 'app', example: 'ngrok' }),
+          queryParam({ name: 'bucket', example: 'extras' }),
+        ],
+      },
     },
-    {
-      title: 'Scoop Version (extras bucket)',
-      namedParams: { app: 'dnspy' },
-      queryParams: { bucket: 'extras' },
-      staticPreview: this.render({ version: '6.1.4' }),
-    },
-  ]
+  }
 
   static defaultBadgeData = { label: 'scoop' }