migrate examples to openApi part 35; affects [npm] (#9866)

* migrate some services from examples to openApi

* clarify docs on scoped/unscoped packages

services/npm/npm-base.js

@@ -34,6 +34,9 @@ export const queryParamSchema = Joi.object({
   registry_uri: optionalUrl,
 }).required()
 
+export const packageNameDescription =
+  'This may be the name of an unscoped package like `package-name` or a [scoped package](https://docs.npmjs.com/about-scopes) like `@author/package-name`'
+
 // Abstract class for NPM badges which display data about the latest version
 // of a package.
 export default class NpmBase extends BaseJsonService {

services/npm/npm-collaborators.service.js

@@ -1,30 +1,30 @@
+import { pathParam, queryParam } from '../index.js'
 import { renderContributorBadge } from '../contributor-count.js'
-import NpmBase from './npm-base.js'
-
-const keywords = ['node']
+import NpmBase, { packageNameDescription } from './npm-base.js'
 
 export default class NpmCollaborators extends NpmBase {
   static category = 'activity'
 
   static route = this.buildRoute('npm/collaborators', { withTag: false })
 
-  static examples = [
-    {
-      title: 'npm collaborators',
-      pattern: ':packageName',
-      namedParams: { packageName: 'prettier' },
-      staticPreview: this.render({ collaborators: 6 }),
-      keywords,
+  static openApi = {
+    '/npm/collaborators/{packageName}': {
+      get: {
+        summary: 'NPM Collaborators',
+        parameters: [
+          pathParam({
+            name: 'packageName',
+            example: 'prettier',
+            description: packageNameDescription,
+          }),
+          queryParam({
+            name: 'registry_uri',
+            example: 'https://registry.npmjs.com',
+          }),
+        ],
+      },
     },
-    {
-      title: 'npm collaborators',
-      pattern: ':packageName',
-      namedParams: { packageName: 'prettier' },
-      queryParams: { registry_uri: 'https://registry.npmjs.com' },
-      staticPreview: this.render({ collaborators: 6 }),
-      keywords,
-    },
-  ]
+  }
 
   static defaultBadgeData = {
     label: 'npm collaborators',

services/npm/npm-dependency-version.service.js

@@ -1,8 +1,9 @@
+import { pathParam, queryParam } from '../index.js'
 import { getDependencyVersion } from '../package-json-helpers.js'
-import NpmBase from './npm-base.js'
-
-const { queryParamSchema } = NpmBase
-const keywords = ['node']
+import NpmBase, {
+  queryParamSchema,
+  packageNameDescription,
+} from './npm-base.js'
 
 export default class NpmDependencyVersion extends NpmBase {
   static category = 'platform-support'
@@ -14,89 +15,55 @@ export default class NpmDependencyVersion extends NpmBase {
     queryParamSchema,
   }
 
-  static examples = [
-    {
-      title: 'npm peer dependency version',
-      pattern: ':packageName/peer/:dependency',
-      namedParams: {
-        packageName: 'react-boxplot',
-        dependency: 'prop-types',
+  static openApi = {
+    '/npm/dependency-version/{packageName}/{dependency}': {
+      get: {
+        summary: 'NPM (prod) Dependency Version',
+        parameters: [
+          pathParam({
+            name: 'packageName',
+            example: 'react-boxplot',
+            description: packageNameDescription,
+          }),
+          pathParam({
+            name: 'dependency',
+            example: 'simple-statistics',
+            description: packageNameDescription,
+          }),
+          queryParam({
+            name: 'registry_uri',
+            example: 'https://registry.npmjs.com',
+          }),
+        ],
       },
-      staticPreview: this.render({
-        dependency: 'prop-types',
-        range: '^15.5.4',
-      }),
-      keywords,
     },
-    {
-      title: 'npm peer dependency version (scoped)',
-      pattern: ':scope?/:packageName/peer/:dependencyScope?/:dependency',
-      namedParams: {
-        scope: '@swellaby',
-        packageName: 'eslint-config',
-        dependency: 'eslint',
+    '/npm/dependency-version/{packageName}/{kind}/{dependency}': {
+      get: {
+        summary: 'NPM dev or peer Dependency Version',
+        parameters: [
+          pathParam({
+            name: 'packageName',
+            example: 'react-boxplot',
+            description: packageNameDescription,
+          }),
+          pathParam({
+            name: 'kind',
+            example: 'dev',
+            schema: { type: 'string', enum: this.getEnum('kind') },
+          }),
+          pathParam({
+            name: 'dependency',
+            example: 'prop-types',
+            description: packageNameDescription,
+          }),
+          queryParam({
+            name: 'registry_uri',
+            example: 'https://registry.npmjs.com',
+          }),
+        ],
       },
-      staticPreview: this.render({
-        dependency: 'eslint',
-        range: '^3.0.0',
-      }),
-      keywords,
     },
-    {
-      title: 'npm dev dependency version',
-      pattern: ':packageName/dev/:dependency',
-      namedParams: {
-        packageName: 'react-boxplot',
-        dependency: 'eslint-config-standard',
-      },
-      staticPreview: this.render({
-        dependency: 'eslint-config-standard',
-        range: '^12.0.0',
-      }),
-      keywords,
-    },
-    {
-      title: 'npm dev dependency version (scoped)',
-      pattern: ':scope?/:packageName/dev/:dependencyScope?/:dependency',
-      namedParams: {
-        packageName: 'mocha',
-        dependencyScope: '@mocha',
-        dependency: 'contributors',
-      },
-      staticPreview: this.render({
-        dependency: '@mocha/contributors',
-        range: '^1.0.3',
-      }),
-      keywords,
-    },
-    {
-      title: 'npm (prod) dependency version',
-      pattern: ':packageName/:dependency',
-      namedParams: {
-        packageName: 'react-boxplot',
-        dependency: 'simple-statistics',
-      },
-      staticPreview: this.render({
-        dependency: 'simple-statistics',
-        range: '^6.1.1',
-      }),
-      keywords,
-    },
-    {
-      title: 'npm (prod) dependency version (scoped)',
-      pattern: ':scope?/:packageName/:dependencyScope?/:dependency',
-      namedParams: {
-        packageName: 'got',
-        dependencyScope: '@sindresorhus',
-        dependency: 'is',
-      },
-      staticPreview: this.render({
-        dependency: '@sindresorhus/is',
-        range: '^0.15.0',
-      }),
-      keywords,
-    },
-  ]
+  }
 
   static defaultBadgeData = {
     label: 'dependency',

services/npm/npm-downloads.service.js

@@ -1,7 +1,8 @@
 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'
+import { packageNameDescription } from './npm-base.js'
 
 // https://github.com/npm/registry/blob/master/docs/download-counts.md#output
 const pointResponseSchema = Joi.object({
@@ -50,14 +51,26 @@ export default class NpmDownloads extends BaseJsonService {
     pattern: ':interval(dw|dm|dy|dt)/:scope(@.+)?/:packageName',
   }
 
-  static examples = [
-    {
-      title: 'npm',
-      namedParams: { interval: 'dw', packageName: 'localeval' },
-      staticPreview: this.render({ interval: 'dw', downloadCount: 30000 }),
-      keywords: ['node'],
+  static openApi = {
+    '/npm/{interval}/{packageName}': {
+      get: {
+        summary: 'NPM Downloads',
+        parameters: pathParams(
+          {
+            name: 'interval',
+            example: 'dw',
+            description: 'Weekly, Monthly, Yearly, or Total downloads',
+            schema: { type: 'string', enum: this.getEnum('interval') },
+          },
+          {
+            name: 'packageName',
+            example: 'localeval',
+            description: packageNameDescription,
+          },
+        ),
+      },
     },
-  ]
+  }
 
   // For testing.
   static _intervalMap = intervalMap

services/npm/npm-license.service.js

@@ -1,29 +1,31 @@
+import { pathParam, queryParam } from '../index.js'
 import { renderLicenseBadge } from '../licenses.js'
 import toArray from '../../core/base-service/to-array.js'
-import NpmBase from './npm-base.js'
+import NpmBase, { packageNameDescription } from './npm-base.js'
 
 export default class NpmLicense extends NpmBase {
   static category = 'license'
 
   static route = this.buildRoute('npm/l', { withTag: false })
 
-  static examples = [
-    {
-      title: 'NPM',
-      pattern: ':packageName',
-      namedParams: { packageName: 'express' },
-      staticPreview: this.render({ licenses: ['MIT'] }),
-      keywords: ['node'],
+  static openApi = {
+    '/npm/l/{packageName}': {
+      get: {
+        summary: 'NPM License',
+        parameters: [
+          pathParam({
+            name: 'packageName',
+            example: 'express',
+            description: packageNameDescription,
+          }),
+          queryParam({
+            name: 'registry_uri',
+            example: 'https://registry.npmjs.com',
+          }),
+        ],
+      },
     },
-    {
-      title: 'NPM',
-      pattern: ':packageName',
-      namedParams: { packageName: 'express' },
-      queryParams: { registry_uri: 'https://registry.npmjs.com' },
-      staticPreview: this.render({ licenses: ['MIT'] }),
-      keywords: ['node'],
-    },
-  ]
+  }
 
   static render({ licenses }) {
     return renderLicenseBadge({ licenses })

services/npm/npm-type-definitions.service.js

@@ -1,5 +1,5 @@
-import { pathParams } from '../index.js'
-import NpmBase from './npm-base.js'
+import { pathParam, queryParam } from '../index.js'
+import NpmBase, { packageNameDescription } from './npm-base.js'
 
 // For this badge to correctly detect type definitions, either the relevant
 // dependencies must be declared, or the `types` key must be set in
@@ -12,11 +12,18 @@ export default class NpmTypeDefinitions extends NpmBase {
   static openApi = {
     '/npm/types/{packageName}': {
       get: {
-        summary: 'npm type definitions',
-        parameters: pathParams({
-          name: 'packageName',
-          example: 'chalk',
-        }),
+        summary: 'NPM Type Definitions',
+        parameters: [
+          pathParam({
+            name: 'packageName',
+            example: 'chalk',
+            description: packageNameDescription,
+          }),
+          queryParam({
+            name: 'registry_uri',
+            example: 'https://registry.npmjs.com',
+          }),
+        ],
       },
     },
   }

services/npm/npm-version.service.js

@@ -1,9 +1,7 @@
 import Joi from 'joi'
 import { renderVersionBadge } from '../version.js'
-import { NotFound } from '../index.js'
-import NpmBase from './npm-base.js'
-
-const keywords = ['node']
+import { NotFound, pathParam, queryParam } from '../index.js'
+import NpmBase, { packageNameDescription } from './npm-base.js'
 
 // Joi.string should be a semver.
 const schema = Joi.object()
@@ -16,44 +14,44 @@ export default class NpmVersion extends NpmBase {
 
   static route = this.buildRoute('npm/v', { withTag: true })
 
-  static examples = [
-    {
-      title: 'npm',
-      pattern: ':packageName',
-      namedParams: { packageName: 'npm' },
-      staticPreview: this.render({ version: '6.3.0' }),
-      keywords,
+  static openApi = {
+    '/npm/v/{packageName}': {
+      get: {
+        summary: 'NPM Version',
+        parameters: [
+          pathParam({
+            name: 'packageName',
+            example: 'npm',
+            description: packageNameDescription,
+          }),
+          queryParam({
+            name: 'registry_uri',
+            example: 'https://registry.npmjs.com',
+          }),
+        ],
+      },
     },
-    {
-      title: 'npm (scoped)',
-      pattern: ':scope/:packageName',
-      namedParams: { scope: '@cycle', packageName: 'core' },
-      staticPreview: this.render({ version: '7.0.0' }),
-      keywords,
+    '/npm/v/{packageName}/{tag}': {
+      get: {
+        summary: 'NPM Version (with dist tag)',
+        parameters: [
+          pathParam({
+            name: 'packageName',
+            example: 'npm',
+            description: packageNameDescription,
+          }),
+          pathParam({
+            name: 'tag',
+            example: 'next-8',
+          }),
+          queryParam({
+            name: 'registry_uri',
+            example: 'https://registry.npmjs.com',
+          }),
+        ],
+      },
     },
-    {
-      title: 'npm (tag)',
-      pattern: ':packageName/:tag',
-      namedParams: { packageName: 'npm', tag: 'next-8' },
-      staticPreview: this.render({ tag: 'latest', version: '6.3.0' }),
-      keywords,
-    },
-    {
-      title: 'npm (custom registry)',
-      pattern: ':packageName/:tag',
-      namedParams: { packageName: 'npm', tag: 'next-8' },
-      queryParams: { registry_uri: 'https://registry.npmjs.com' },
-      staticPreview: this.render({ tag: 'latest', version: '7.0.0' }),
-      keywords,
-    },
-    {
-      title: 'npm (scoped with tag)',
-      pattern: ':scope/:packageName/:tag',
-      namedParams: { scope: '@cycle', packageName: 'core', tag: 'canary' },
-      staticPreview: this.render({ tag: 'latest', version: '6.3.0' }),
-      keywords,
-    },
-  ]
+  }
 
   static defaultBadgeData = {
     label: 'npm',