migrate examples to openApi part 17; affects [buildkite cii codeship crates jsdelivr npms] and bundlephobia (#9584)

* update crates service test

* migrate some services from examples to openApi

* migrate crates from examples to openApi, improve titles

* explain what hd,hw,hm,hy actually mean

* improve descriptions

services/buildkite/buildkite.service.js

@@ -1,6 +1,6 @@
 import Joi from 'joi'
 import { isBuildStatus, renderBuildStatusBadge } from '../build-status.js'
-import { BaseJsonService } from '../index.js'
+import { BaseJsonService, pathParams } from '../index.js'
 
 // unknown is a valid 'other' status for Buildkite
 const schema = Joi.object({
@@ -11,25 +11,32 @@ export default class Buildkite extends BaseJsonService {
   static category = 'build'
   static route = { base: 'buildkite', pattern: ':identifier/:branch*' }
 
-  static examples = [
+  static openApi = {
-    {
+    '/buildkite/{identifier}': {
-      title: 'Buildkite',
+      get: {
-      pattern: ':identifier',
+        summary: 'Buildkite',
-      namedParams: {
+        parameters: pathParams({
-        identifier: '3826789cf8890b426057e6fe1c4e683bdf04fa24d498885489',
+          name: 'identifier',
+          example: '3826789cf8890b426057e6fe1c4e683bdf04fa24d498885489',
+        }),
       },
-      staticPreview: renderBuildStatusBadge({ status: 'passing' }),
     },
-    {
+    '/buildkite/{identifier}/{branch}': {
-      title: 'Buildkite (branch)',
+      get: {
-      pattern: ':identifier/:branch',
+        summary: 'Buildkite (branch)',
-      namedParams: {
+        parameters: pathParams(
-        identifier: '3826789cf8890b426057e6fe1c4e683bdf04fa24d498885489',
+          {
-        branch: 'master',
+            name: 'identifier',
+            example: '3826789cf8890b426057e6fe1c4e683bdf04fa24d498885489',
+          },
+          {
+            name: 'branch',
+            example: 'master',
+          },
+        ),
       },
-      staticPreview: renderBuildStatusBadge({ status: 'passing' }),
     },
-  ]
+  }
 
   static defaultBadgeData = { label: 'build' }
 

services/bundlephobia/bundlephobia.service.js

@@ -1,14 +1,15 @@
 import Joi from 'joi'
 import prettyBytes from 'pretty-bytes'
 import { nonNegativeInteger } from '../validators.js'
-import { BaseJsonService } from '../index.js'
+import { BaseJsonService, pathParams } from '../index.js'
 
 const schema = Joi.object({
   size: nonNegativeInteger,
   gzip: nonNegativeInteger,
 }).required()
 
-const keywords = ['node', 'bundlephobia']
+const description =
+  '[Bundlephobia](https://bundlephobia.com) lets you understand the size of a javascript package from NPM before it becomes a part of your bundle.'
 
 export default class Bundlephobia extends BaseJsonService {
   static category = 'size'
@@ -18,52 +19,92 @@ export default class Bundlephobia extends BaseJsonService {
     pattern: ':format(min|minzip)/:scope(@[^/]+)?/:packageName/:version?',
   }
 
-  static examples = [
+  static openApi = {
-    {
+    '/bundlephobia/{format}/{packageName}': {
-      title: 'npm bundle size',
+      get: {
-      pattern: ':format(min|minzip)/:packageName',
+        summary: 'npm bundle size',
-      namedParams: {
+        description,
-        format: 'min',
+        parameters: pathParams(
-        packageName: 'react',
+          {
+            name: 'format',
+            schema: { type: 'string', enum: this.getEnum('format') },
+            example: 'min',
+          },
+          {
+            name: 'packageName',
+            example: 'react',
+          },
+        ),
       },
-      staticPreview: this.render({ format: 'min', size: 6652 }),
-      keywords,
     },
-    {
+    '/bundlephobia/{format}/{scope}/{packageName}': {
-      title: 'npm bundle size (scoped)',
+      get: {
-      pattern: ':format(min|minzip)/:scope/:packageName',
+        summary: 'npm bundle size (scoped)',
-      namedParams: {
+        description,
-        format: 'min',
+        parameters: pathParams(
-        scope: '@cycle',
+          {
-        packageName: 'core',
+            name: 'format',
+            schema: { type: 'string', enum: this.getEnum('format') },
+            example: 'min',
+          },
+          {
+            name: 'scope',
+            example: '@cycle',
+          },
+          {
+            name: 'packageName',
+            example: 'core',
+          },
+        ),
       },
-      staticPreview: this.render({ format: 'min', size: 3562 }),
-      keywords,
     },
-    {
+    '/bundlephobia/{format}/{packageName}/{version}': {
-      title: 'npm bundle size (version)',
+      get: {
-      pattern: ':format(min|minzip)/:packageName/:version',
+        summary: 'npm bundle size (version)',
-      namedParams: {
+        description,
-        format: 'min',
+        parameters: pathParams(
-        packageName: 'react',
+          {
-        version: '15.0.0',
+            name: 'format',
+            schema: { type: 'string', enum: this.getEnum('format') },
+            example: 'min',
+          },
+          {
+            name: 'packageName',
+            example: 'react',
+          },
+          {
+            name: 'version',
+            example: '15.0.0',
+          },
+        ),
       },
-      staticPreview: this.render({ format: 'min', size: 20535 }),
-      keywords,
     },
-    {
+    '/bundlephobia/{format}/{scope}/{packageName}/{version}': {
-      title: 'npm bundle size (scoped version)',
+      get: {
-      pattern: ':format(min|minzip)/:scope/:packageName/:version',
+        summary: 'npm bundle size (scoped version)',
-      namedParams: {
+        description,
-        format: 'min',
+        parameters: pathParams(
-        scope: '@cycle',
+          {
-        packageName: 'core',
+            name: 'format',
-        version: '7.0.0',
+            schema: { type: 'string', enum: this.getEnum('format') },
+            example: 'min',
+          },
+          {
+            name: 'scope',
+            example: '@cycle',
+          },
+          {
+            name: 'packageName',
+            example: 'core',
+          },
+          {
+            name: 'version',
+            example: '7.0.0',
+          },
+        ),
       },
-      staticPreview: this.render({ format: 'min', size: 3562 }),
-      keywords,
     },
-  ]
+  }
 
   static _cacheLength = 900
 

services/cii-best-practices/cii-best-practices.service.js

@@ -1,14 +1,12 @@
 import Joi from 'joi'
 import { colorScale, coveragePercentage } from '../color-formatters.js'
-import { BaseJsonService } from '../index.js'
+import { BaseJsonService, pathParams } from '../index.js'
 
 const schema = Joi.object({
   badge_level: Joi.string().required(),
   tiered_percentage: Joi.number().required(),
 }).required()
 
-const keywords = ['core infrastructure initiative']
-
 const summaryColorScale = colorScale(
   [10, 20, 30, 40, 50, 60, 70, 80, 90, 100, 200, 300],
   [
@@ -35,37 +33,26 @@ export default class CIIBestPracticesService extends BaseJsonService {
     pattern: ':metric(level|percentage|summary)/:projectId',
   }
 
-  static examples = [
+  static openApi = {
-    {
+    '/cii/{metric}/{projectId}': {
-      title: 'CII Best Practices Level',
+      get: {
-      pattern: 'level/:projectId',
+        summary: 'CII Best Practices',
-      namedParams: {
+        description:
-        projectId: '1',
+          'The Core Infrastructure Initiative (CII) Best Practices badge is a way for Open Source projects to show that they follow best practices',
+        parameters: pathParams(
+          {
+            name: 'metric',
+            example: 'level',
+            schema: { type: 'string', enum: this.getEnum('metric') },
+          },
+          {
+            name: 'projectId',
+            example: '1',
+          },
+        ),
       },
-      staticPreview: this.renderLevelBadge({ level: 'gold' }),
-      keywords,
     },
-    {
+  }
-      title: 'CII Best Practices Tiered Percentage',
-      pattern: 'percentage/:projectId',
-      namedParams: {
-        projectId: '29',
-      },
-      staticPreview: this.renderTieredPercentageBadge({ percentage: 107 }),
-      keywords,
-    },
-    {
-      title: 'CII Best Practices Summary',
-      pattern: 'summary/:projectId',
-      namedParams: {
-        projectId: '33',
-      },
-      staticPreview: this.renderSummaryBadge({ percentage: 94 }),
-      keywords,
-      documentation:
-        'This badge uses the same message and color scale as the native CII one, but with all the configuration and goodness that Shields provides!',
-    },
-  ]
 
   static defaultBadgeData = { label: 'cii' }
 

services/codeship/codeship.service.js

@@ -1,6 +1,6 @@
 import Joi from 'joi'
 import { isBuildStatus, renderBuildStatusBadge } from '../build-status.js'
-import { BaseSvgScrapingService } from '../index.js'
+import { BaseSvgScrapingService, pathParams } from '../index.js'
 
 const schema = Joi.object({
   message: Joi.alternatives()
@@ -28,25 +28,32 @@ export default class Codeship extends BaseSvgScrapingService {
   static category = 'build'
   static route = { base: 'codeship', pattern: ':projectId/:branch*' }
 
-  static examples = [
+  static openApi = {
-    {
+    '/codeship/{projectId}': {
-      title: 'Codeship',
+      get: {
-      pattern: ':projectId',
+        summary: 'Codeship',
-      namedParams: {
+        parameters: pathParams({
-        projectId: 'd6c1ddd0-16a3-0132-5f85-2e35c05e22b1',
+          name: 'projectId',
+          example: 'd6c1ddd0-16a3-0132-5f85-2e35c05e22b1',
+        }),
       },
-      staticPreview: renderBuildStatusBadge({ status: 'passing' }),
     },
-    {
+    '/codeship/{projectId}/{branch}': {
-      title: 'Codeship (branch)',
+      get: {
-      pattern: ':projectId/:branch',
+        summary: 'Codeship (branch)',
-      namedParams: {
+        parameters: pathParams(
-        projectId: '0bdb0440-3af5-0133-00ea-0ebda3a33bf6',
+          {
-        branch: 'master',
+            name: 'projectId',
+            example: '0bdb0440-3af5-0133-00ea-0ebda3a33bf6',
+          },
+          {
+            name: 'branch',
+            example: 'master',
+          },
+        ),
       },
-      staticPreview: renderBuildStatusBadge({ status: 'passing' }),
     },
-  ]
+  }
 
   static defaultBadgeData = { label: 'build' }
 

services/crates/crates-base.js

@@ -2,8 +2,6 @@ import Joi from 'joi'
 import { nonNegativeInteger } from '../validators.js'
 import { BaseJsonService } from '../index.js'
 
-const keywords = ['Rust']
-
 const crateSchema = Joi.object({
   crate: Joi.object({
     downloads: nonNegativeInteger,
@@ -49,4 +47,7 @@ class BaseCratesService extends BaseJsonService {
   }
 }
 
-export { BaseCratesService, keywords }
+const description =
+  '[Crates.io](https://crates.io/) is a package registry for Rust.'
+
+export { BaseCratesService, description }

services/crates/crates-downloads.service.js

@@ -1,6 +1,6 @@
 import { renderDownloadsBadge } from '../downloads.js'
-import { InvalidParameter, NotFound } from '../index.js'
+import { InvalidParameter, NotFound, pathParams } from '../index.js'
-import { BaseCratesService, keywords } from './crates-base.js'
+import { BaseCratesService, description } from './crates-base.js'
 
 export default class CratesDownloads extends BaseCratesService {
   static category = 'downloads'
@@ -9,49 +9,54 @@ export default class CratesDownloads extends BaseCratesService {
     pattern: ':variant(d|dv|dr)/:crate/:version?',
   }
 
-  static examples = [
+  static openApi = {
-    {
+    '/crates/d/{crate}': {
-      title: 'Crates.io',
+      get: {
-      pattern: 'd/:crate',
+        summary: 'Crates.io Total Downloads',
-      namedParams: {
+        description,
-        crate: 'rustc-serialize',
+        parameters: pathParams({
+          name: 'crate',
+          example: 'rustc-serialize',
+        }),
       },
-      staticPreview: this.render({ variant: 'd', downloads: 5000000 }),
-      keywords,
     },
-    {
+    '/crates/dv/{crate}': {
-      title: 'Crates.io (latest)',
+      get: {
-      pattern: 'dv/:crate',
+        summary: 'Crates.io Downloads (latest version)',
-      namedParams: {
+        description,
-        crate: 'rustc-serialize',
+        parameters: pathParams({
+          name: 'crate',
+          example: 'rustc-serialize',
+        }),
       },
-      staticPreview: this.render({ variant: 'dv', downloads: 2000000 }),
-      keywords,
     },
-    {
+    '/crates/dv/{crate}/{version}': {
-      title: 'Crates.io (version)',
+      get: {
-      pattern: 'dv/:crate/:version',
+        summary: 'Crates.io Downloads (version)',
-      namedParams: {
+        description,
-        crate: 'rustc-serialize',
+        parameters: pathParams(
-        version: '0.3.24',
+          {
+            name: 'crate',
+            example: 'rustc-serialize',
+          },
+          {
+            name: 'version',
+            example: '0.3.24',
+          },
+        ),
       },
-      staticPreview: this.render({
-        variant: 'dv',
-        downloads: 2000000,
-        version: '0.3.24',
-      }),
-      keywords,
     },
-    {
+    '/crates/dr/{crate}': {
-      title: 'Crates.io (recent)',
+      get: {
-      pattern: 'dr/:crate',
+        summary: 'Crates.io Downloads (recent)',
-      namedParams: {
+        description,
-        crate: 'rustc-serialize',
+        parameters: pathParams({
+          name: 'crate',
+          example: 'rustc-serialize',
+        }),
       },
-      staticPreview: this.render({ variant: 'dr', downloads: 2000000 }),
-      keywords,
     },
-  ]
+  }
 
   static render({ variant, downloads, version }) {
     let labelOverride

services/crates/crates-license.service.js

@@ -1,26 +1,38 @@
-import { InvalidResponse } from '../index.js'
+import { InvalidResponse, pathParams } from '../index.js'
-import { BaseCratesService, keywords } from './crates-base.js'
+import { BaseCratesService, description } from './crates-base.js'
 
 export default class CratesLicense extends BaseCratesService {
   static category = 'license'
   static route = { base: 'crates/l', pattern: ':crate/:version?' }
 
-  static examples = [
+  static openApi = {
-    {
+    '/crates/l/{crate}': {
-      title: 'Crates.io',
+      get: {
-      pattern: ':crate',
+        summary: 'Crates.io License',
-      namedParams: { crate: 'rustc-serialize' },
+        description,
-      staticPreview: this.render({ license: 'MIT/Apache-2.0' }),
+        parameters: pathParams({
-      keywords,
+          name: 'crate',
+          example: 'rustc-serialize',
+        }),
+      },
     },
-    {
+    '/crates/l/{crate}/{version}': {
-      title: 'Crates.io',
+      get: {
-      pattern: ':crate/:version',
+        summary: 'Crates.io License (version)',
-      namedParams: { crate: 'rustc-serialize', version: '0.3.24' },
+        description,
-      staticPreview: this.render({ license: 'MIT/Apache-2.0' }),
+        parameters: pathParams(
-      keywords,
+          {
+            name: 'crate',
+            example: 'rustc-serialize',
+          },
+          {
+            name: 'version',
+            example: '0.3.24',
+          },
+        ),
+      },
     },
-  ]
+  }
 
   static defaultBadgeData = { label: 'license', color: 'blue' }
 

services/crates/crates-license.tester.js

@@ -16,7 +16,7 @@ t.create('license (not found)')
 // https://github.com/badges/shields/issues/7073
 t.create('license (null licenses in history)')
   .get('/stun.json')
-  .expectBadge({ label: 'license', message: 'MIT/Apache-2.0' })
+  .expectBadge({ label: 'license', message: 'MIT OR Apache-2.0' })
 
 t.create('license (version with null license)')
   .get('/stun/0.0.1.json')

services/crates/crates-version.service.js

@@ -1,19 +1,23 @@
 import { renderVersionBadge } from '../version.js'
-import { InvalidResponse } from '../index.js'
+import { InvalidResponse, pathParams } from '../index.js'
-import { BaseCratesService, keywords } from './crates-base.js'
+import { BaseCratesService, description } from './crates-base.js'
 
 export default class CratesVersion extends BaseCratesService {
   static category = 'version'
   static route = { base: 'crates/v', pattern: ':crate' }
 
-  static examples = [
+  static openApi = {
-    {
+    '/crates/v/{crate}': {
-      title: 'Crates.io',
+      get: {
-      namedParams: { crate: 'rustc-serialize' },
+        summary: 'Crates.io Version',
-      staticPreview: renderVersionBadge({ version: '0.3.24' }),
+        description,
-      keywords,
+        parameters: pathParams({
+          name: 'crate',
+          example: 'rustc-serialize',
+        }),
+      },
     },
-  ]
+  }
 
   transform(json) {
     if (json.errors) {

services/jsdelivr/jsdelivr-hits-github.service.js

@@ -16,6 +16,7 @@ export default class JsDelivrHitsGitHub extends BaseJsDelivrService {
             name: 'period',
             example: 'hm',
             schema: { type: 'string', enum: this.getEnum('period') },
+            description: 'Hits per day, week, month or year',
           },
           {
             name: 'user',

services/jsdelivr/jsdelivr-hits-npm.service.js

@@ -1,3 +1,4 @@
+import { pathParams } from '../index.js'
 import { schema, periodMap, BaseJsDelivrService } from './jsdelivr-base.js'
 
 export default class JsDelivrHitsNPM extends BaseJsDelivrService {
@@ -6,27 +7,46 @@ export default class JsDelivrHitsNPM extends BaseJsDelivrService {
     pattern: ':period(hd|hw|hm|hy)/:scope(@[^/]+)?/:packageName',
   }
 
-  static examples = [
+  static openApi = {
-    {
+    '/jsdelivr/npm/{period}/{packageName}': {
-      title: 'jsDelivr hits (npm)',
+      get: {
-      pattern: ':period(hd|hw|hm|hy)/:packageName',
+        summary: 'jsDelivr hits (npm)',
-      namedParams: {
+        parameters: pathParams(
-        period: 'hm',
+          {
-        packageName: 'jquery',
+            name: 'period',
+            schema: { type: 'string', enum: this.getEnum('period') },
+            example: 'hm',
+            description: 'Hits per day, week, month or year',
+          },
+          {
+            name: 'packageName',
+            example: 'fire',
+          },
+        ),
       },
-      staticPreview: this.render({ period: 'hm', hits: 920101789 }),
     },
-    {
+    '/jsdelivr/npm/{period}/{scope}/{packageName}': {
-      title: 'jsDelivr hits (npm scoped)',
+      get: {
-      pattern: ':period(hd|hw|hm|hy)/:scope?/:packageName',
+        summary: 'jsDelivr hits (npm scoped)',
-      namedParams: {
+        parameters: pathParams(
-        period: 'hm',
+          {
-        scope: '@angular',
+            name: 'period',
-        packageName: 'fire',
+            schema: { type: 'string', enum: this.getEnum('period') },
+            example: 'hm',
+            description: 'Hits per day, week, month or year',
+          },
+          {
+            name: 'scope',
+            example: '@angular',
+          },
+          {
+            name: 'packageName',
+            example: 'fire',
+          },
+        ),
       },
-      staticPreview: this.render({ period: 'hm', hits: 94123 }),
     },
-  ]
+  }
 
   async fetch({ period, packageName }) {
     return this._requestJson({

services/npms-io/npms-io-score.service.js

@@ -1,5 +1,5 @@
 import Joi from 'joi'
-import { BaseJsonService } from '../index.js'
+import { BaseJsonService, pathParams } from '../index.js'
 import { coveragePercentage } from '../color-formatters.js'
 
 // https://api-docs.npms.io/#api-Package-GetPackageInfo
@@ -15,7 +15,8 @@ const responseSchema = Joi.object({
   }),
 }).required()
 
-const keywords = ['node', 'npm score']
+const description =
+  '[npms.io](https://npms.io) holds statistics for javascript packages.'
 
 export default class NpmsIOScore extends BaseJsonService {
   static category = 'analysis'
@@ -26,37 +27,46 @@ export default class NpmsIOScore extends BaseJsonService {
       ':type(final-score|maintenance-score|popularity-score|quality-score)/:scope(@.+)?/:packageName',
   }
 
-  static examples = [
+  static openApi = {
-    {
+    '/npms-io/{type}/{packageName}': {
-      title: 'npms.io (final)',
+      get: {
-      namedParams: { type: 'final-score', packageName: 'egg' },
+        summary: 'npms.io',
-      staticPreview: this.render({ score: 0.9711 }),
+        description,
-      keywords,
+        parameters: pathParams(
-    },
+          {
-    {
+            name: 'type',
-      title: 'npms.io (popularity)',
+            schema: { type: 'string', enum: this.getEnum('type') },
-      pattern: ':type/:scope/:packageName',
+            example: 'maintenance-score',
-      namedParams: {
+          },
-        type: 'popularity-score',
+          {
-        scope: '@vue',
+            name: 'packageName',
-        packageName: 'cli',
+            example: 'command',
+          },
+        ),
       },
-      staticPreview: this.render({ type: 'popularity', score: 0.89 }),
-      keywords,
     },
-    {
+    '/npms-io/{type}/{scope}/{packageName}': {
-      title: 'npms.io (quality)',
+      get: {
-      namedParams: { type: 'quality-score', packageName: 'egg' },
+        summary: 'npms.io (scoped package)',
-      staticPreview: this.render({ type: 'quality', score: 0.98 }),
+        description,
-      keywords,
+        parameters: pathParams(
+          {
+            name: 'type',
+            schema: { type: 'string', enum: this.getEnum('type') },
+            example: 'maintenance-score',
+          },
+          {
+            name: 'scope',
+            example: '@vue',
+          },
+          {
+            name: 'packageName',
+            example: 'cli',
+          },
+        ),
+      },
     },
-    {
+  }
-      title: 'npms.io (maintenance)',
-      namedParams: { type: 'maintenance-score', packageName: 'command' },
-      staticPreview: this.render({ type: 'maintenance', score: 0.222 }),
-      keywords,
-    },
-  ]
 
   static defaultBadgeData = {
     label: 'score',