migrate examples to openApi part 18; affects [conda feedz gem openvsx readthedocs] github (#9607)

* migrate some services from examples to openApi

* fixup which --> variant param rename

* improve descriptions

* migrate gem version

* improve descriptions for ruby gems

* standardise on packageName for all conda badges

services/conda/conda-base.js

@@ -17,10 +17,10 @@ const condaSchema = Joi.object({
 export default class BaseCondaService extends BaseJsonService {
   static defaultBadgeData = { label: 'conda' }
 
-  async fetch({ channel, pkg }) {
+  async fetch({ channel, packageName }) {
     return this._requestJson({
       schema: condaSchema,
-      url: `https://api.anaconda.org/package/${channel}/${pkg}`,
+      url: `https://api.anaconda.org/package/${channel}/${packageName}`,
     })
   }
 }

services/conda/conda-downloads.service.js

@@ -4,10 +4,13 @@ import BaseCondaService from './conda-base.js'
 
 export default class CondaDownloads extends BaseCondaService {
   static category = 'downloads'
-  static route = { base: 'conda', pattern: ':variant(d|dn)/:channel/:pkg' }
+  static route = {
+    base: 'conda',
+    pattern: ':variant(d|dn)/:channel/:packageName',
+  }
 
   static openApi = {
-    '/conda/{variant}/{channel}/{package}': {
+    '/conda/{variant}/{channel}/{packageName}': {
       get: {
         summary: 'Conda Downloads',
         parameters: pathParams(
@@ -21,7 +24,7 @@ export default class CondaDownloads extends BaseCondaService {
             example: 'conda-forge',
           },
           {
-            name: 'package',
+            name: 'packageName',
             example: 'python',
           },
         ),
@@ -34,8 +37,8 @@ export default class CondaDownloads extends BaseCondaService {
     return renderDownloadsBadge({ downloads, labelOverride })
   }
 
-  async handle({ variant, channel, pkg }) {
-    const json = await this.fetch({ channel, pkg })
+  async handle({ variant, channel, packageName }) {
+    const json = await this.fetch({ channel, packageName })
     const downloads = json.files.reduce(
       (total, file) => total + file.ndownloads,
       0,

services/conda/conda-license.service.js

@@ -10,10 +10,10 @@ const schema = Joi.object({
 
 export default class CondaLicense extends BaseCondaService {
   static category = 'license'
-  static route = { base: 'conda', pattern: 'l/:channel/:pkg' }
+  static route = { base: 'conda', pattern: 'l/:channel/:packageName' }
 
   static openApi = {
-    '/conda/l/{channel}/{package}': {
+    '/conda/l/{channel}/{packageName}': {
       get: {
         summary: 'Conda - License',
         parameters: pathParams(
@@ -22,7 +22,7 @@ export default class CondaLicense extends BaseCondaService {
             example: 'conda-forge',
           },
           {
-            name: 'package',
+            name: 'packageName',
             example: 'setuptools',
           },
         ),
@@ -36,10 +36,10 @@ export default class CondaLicense extends BaseCondaService {
     return renderLicenseBadge({ licenses })
   }
 
-  async handle({ channel, pkg }) {
+  async handle({ channel, packageName }) {
     const json = await this._requestJson({
       schema,
-      url: `https://api.anaconda.org/package/${channel}/${pkg}`,
+      url: `https://api.anaconda.org/package/${channel}/${packageName}`,
     })
     return this.constructor.render({
       licenses: toArray(json.license),

services/conda/conda-platform.service.js

@@ -3,10 +3,13 @@ import BaseCondaService from './conda-base.js'
 
 export default class CondaPlatform extends BaseCondaService {
   static category = 'platform-support'
-  static route = { base: 'conda', pattern: ':variant(p|pn)/:channel/:pkg' }
+  static route = {
+    base: 'conda',
+    pattern: ':variant(p|pn)/:channel/:packageName',
+  }
 
   static openApi = {
-    '/conda/{variant}/{channel}/{package}': {
+    '/conda/{variant}/{channel}/{packageName}': {
       get: {
         summary: 'Conda Platform',
         parameters: pathParams(
@@ -20,7 +23,7 @@ export default class CondaPlatform extends BaseCondaService {
             example: 'conda-forge',
           },
           {
-            name: 'package',
+            name: 'packageName',
             example: 'python',
           },
         ),
@@ -35,8 +38,8 @@ export default class CondaPlatform extends BaseCondaService {
     }
   }
 
-  async handle({ variant, channel, pkg }) {
-    const json = await this.fetch({ channel, pkg })
+  async handle({ variant, channel, packageName }) {
+    const json = await this.fetch({ channel, packageName })
     return this.constructor.render({ variant, platforms: json.conda_platforms })
   }
 }

services/conda/conda-version.service.js

@@ -1,33 +1,37 @@
+import { pathParams } from '../index.js'
 import { addv as versionText } from '../text-formatters.js'
 import { version as versionColor } from '../color-formatters.js'
 import BaseCondaService from './conda-base.js'
 
 export default class CondaVersion extends BaseCondaService {
   static category = 'version'
-  static route = { base: 'conda', pattern: ':variant(v|vn)/:channel/:pkg' }
+  static route = {
+    base: 'conda',
+    pattern: ':variant(v|vn)/:channel/:packageName',
+  }
 
-  static examples = [
-    {
-      title: 'Conda',
-      namedParams: { channel: 'conda-forge', package: 'python' },
-      pattern: 'v/:channel/:package',
-      staticPreview: this.render({
-        variant: 'v',
-        channel: 'conda-forge',
-        version: '3.7.1',
-      }),
+  static openApi = {
+    '/conda/{variant}/{channel}/{packageName}': {
+      get: {
+        summary: 'Conda Version',
+        parameters: pathParams(
+          {
+            name: 'variant',
+            example: 'vn',
+            schema: { type: 'string', enum: this.getEnum('variant') },
+          },
+          {
+            name: 'channel',
+            example: 'conda-forge',
+          },
+          {
+            name: 'packageName',
+            example: 'python',
+          },
+        ),
+      },
     },
-    {
-      title: 'Conda (channel only)',
-      namedParams: { channel: 'conda-forge', package: 'python' },
-      pattern: 'vn/:channel/:package',
-      staticPreview: this.render({
-        variant: 'vn',
-        channel: 'conda-forge',
-        version: '3.7.1',
-      }),
-    },
-  ]
+  }
 
   static render({ variant, channel, version }) {
     return {
@@ -37,8 +41,8 @@ export default class CondaVersion extends BaseCondaService {
     }
   }
 
-  async handle({ variant, channel, pkg }) {
-    const json = await this.fetch({ channel, pkg })
+  async handle({ variant, channel, packageName }) {
+    const json = await this.fetch({ channel, packageName })
     return this.constructor.render({
       variant,
       channel,

services/feedz/feedz.service.js

@@ -1,5 +1,5 @@
 import Joi from 'joi'
-import { BaseJsonService, NotFound } from '../index.js'
+import { BaseJsonService, NotFound, pathParams } from '../index.js'
 import {
   renderVersionBadge,
   searchServiceUrl,
@@ -29,31 +29,36 @@ class FeedzVersionService extends BaseJsonService {
 
   static route = {
     base: 'feedz',
-    pattern: ':which(v|vpre)/:organization/:repository/:packageName',
+    pattern: ':variant(v|vpre)/:organization/:repository/:packageName',
   }
 
-  static examples = [
-    {
-      title: 'Feedz',
-      pattern: 'v/:organization/:repository/:packageName',
-      namedParams: {
-        organization: 'shieldstests',
-        repository: 'mongodb',
-        packageName: 'MongoDB.Driver.Core',
+  static openApi = {
+    '/feedz/{variant}/{organization}/{repository}/{packageName}': {
+      get: {
+        summary: 'Feedz Version',
+        parameters: pathParams(
+          {
+            name: 'variant',
+            example: 'v',
+            description: 'version or version including pre-releases',
+            schema: { type: 'string', enum: this.getEnum('variant') },
+          },
+          {
+            name: 'organization',
+            example: 'shieldstests',
+          },
+          {
+            name: 'repository',
+            example: 'mongodb',
+          },
+          {
+            name: 'packageName',
+            example: 'MongoDB.Driver.Core',
+          },
+        ),
       },
-      staticPreview: this.render({ version: '2.10.4' }),
     },
-    {
-      title: 'Feedz (with prereleases)',
-      pattern: 'vpre/:organization/:repository/:packageName',
-      namedParams: {
-        organization: 'shieldstests',
-        repository: 'mongodb',
-        packageName: 'MongoDB.Driver.Core',
-      },
-      staticPreview: this.render({ version: '2.11.0-beta2' }),
-    },
-  ]
+  }
 
   static defaultBadgeData = {
     label: 'feedz',
@@ -111,8 +116,8 @@ class FeedzVersionService extends BaseJsonService {
     }
   }
 
-  async handle({ which, organization, repository, packageName }) {
-    const includePrereleases = which === 'vpre'
+  async handle({ variant, organization, repository, packageName }) {
+    const includePrereleases = variant === 'vpre'
     const baseUrl = this.apiUrl({ organization, repository })
     const json = await this.fetch({ baseUrl, packageName })
     const fetchedJson = await this.fetchItems({ json })

services/gem/gem-downloads.service.js

@@ -3,9 +3,13 @@ import Joi from 'joi'
 import { renderDownloadsBadge } from '../downloads.js'
 import { latest as latestVersion } from '../version.js'
 import { nonNegativeInteger } from '../validators.js'
-import { BaseJsonService, InvalidParameter, InvalidResponse } from '../index.js'
-
-const keywords = ['ruby']
+import {
+  BaseJsonService,
+  InvalidParameter,
+  InvalidResponse,
+  pathParams,
+} from '../index.js'
+import { description } from './gem-helpers.js'
 
 const gemSchema = Joi.object({
   downloads: nonNegativeInteger,
@@ -26,56 +30,44 @@ const versionSchema = Joi.array()
 export default class GemDownloads extends BaseJsonService {
   static category = 'downloads'
   static route = { base: 'gem', pattern: ':variant(dt|dtv|dv)/:gem/:version?' }
-  static examples = [
-    {
-      title: 'Gem',
-      pattern: 'dv/:gem/:version',
-      namedParams: {
-        gem: 'rails',
-        version: 'stable',
+  static openApi = {
+    '/gem/dt/{gem}': {
+      get: {
+        summary: 'Gem Total Downloads',
+        description,
+        parameters: pathParams({
+          name: 'gem',
+          example: 'rails',
+        }),
       },
-      staticPreview: this.render({
-        variant: 'dv',
-        version: 'stable',
-        downloads: 70000,
-      }),
-      keywords,
     },
-    {
-      title: 'Gem',
-      pattern: 'dv/:gem/:version',
-      namedParams: {
-        gem: 'rails',
-        version: '4.1.0',
+    '/gem/dtv/{gem}': {
+      get: {
+        summary: 'Gem Downloads (for latest version)',
+        description,
+        parameters: pathParams({
+          name: 'gem',
+          example: 'rails',
+        }),
       },
-      staticPreview: this.render({
-        variant: 'dv',
-        version: '4.1.0',
-        downloads: 50000,
-      }),
-      keywords,
     },
-    {
-      title: 'Gem',
-      pattern: 'dtv/:gem',
-      namedParams: { gem: 'rails' },
-      staticPreview: this.render({
-        variant: 'dtv',
-        downloads: 70000,
-      }),
-      keywords,
+    '/gem/dv/{gem}/{version}': {
+      get: {
+        summary: 'Gem Downloads (for specified version)',
+        description,
+        parameters: pathParams(
+          {
+            name: 'gem',
+            example: 'rails',
+          },
+          {
+            name: 'version',
+            example: '4.1.0',
+          },
+        ),
+      },
     },
-    {
-      title: 'Gem',
-      pattern: 'dt/:gem',
-      namedParams: { gem: 'rails' },
-      staticPreview: this.render({
-        variant: 'dt',
-        downloads: 900000,
-      }),
-      keywords,
-    },
-  ]
+  }
 
   static defaultBadgeData = { label: 'downloads' }
 

services/gem/gem-helpers.js

@@ -1,5 +1,8 @@
 import { valid, maxSatisfying, prerelease } from '@renovatebot/ruby-semver'
 
+const description =
+  '[Ruby Gems](https://rubygems.org/) is a registry for ruby libraries'
+
 function latest(versions) {
   // latest Ruby Gems version, including pre-releases
   return maxSatisfying(versions, '>0')
@@ -22,4 +25,4 @@ function versionColor(version) {
   return 'blue'
 }
 
-export { latest, versionColor }
+export { description, latest, versionColor }

services/gem/gem-owner.service.js

@@ -2,6 +2,7 @@ import Joi from 'joi'
 import { floorCount as floorCountColor } from '../color-formatters.js'
 import { metric } from '../text-formatters.js'
 import { BaseJsonService, pathParams } from '../index.js'
+import { description } from './gem-helpers.js'
 
 const ownerSchema = Joi.array().required()
 
@@ -12,6 +13,7 @@ export default class GemOwner extends BaseJsonService {
     '/gem/u/{user}': {
       get: {
         summary: 'Gem Owner',
+        description,
         parameters: pathParams({
           name: 'user',
           example: 'raphink',

services/gem/gem-rank.service.js

@@ -1,9 +1,8 @@
 import Joi from 'joi'
 import { floorCount } from '../color-formatters.js'
 import { ordinalNumber } from '../text-formatters.js'
-import { BaseJsonService, InvalidResponse } from '../index.js'
-
-const keywords = ['ruby']
+import { BaseJsonService, InvalidResponse, pathParams } from '../index.js'
+import { description } from './gem-helpers.js'
 
 const totalSchema = Joi.array()
   .items(
@@ -25,26 +24,26 @@ const dailySchema = Joi.array()
 export default class GemRank extends BaseJsonService {
   static category = 'downloads'
   static route = { base: 'gem', pattern: ':period(rt|rd)/:gem' }
-  static examples = [
-    {
-      title: 'Gem download rank',
-      pattern: 'rt/:gem',
-      namedParams: {
-        gem: 'puppet',
+  static openApi = {
+    '/gem/{period}/{gem}': {
+      get: {
+        summary: 'Gem download rank',
+        description,
+        parameters: pathParams(
+          {
+            name: 'period',
+            example: 'rt',
+            description: 'total or daily ranking',
+            schema: { type: 'string', enum: this.getEnum('period') },
+          },
+          {
+            name: 'gem',
+            example: 'puppet',
+          },
+        ),
       },
-      staticPreview: this.render({ period: 'rt', rank: 332 }),
-      keywords,
     },
-    {
-      title: 'Gem download rank (daily)',
-      pattern: 'rd/:gem',
-      namedParams: {
-        gem: 'facter',
-      },
-      staticPreview: this.render({ period: 'rd', rank: 656 }),
-      keywords,
-    },
-  ]
+  }
 
   static defaultBadgeData = { label: 'rank' }
 

services/gem/gem-version.service.js

@@ -1,7 +1,7 @@
 import Joi from 'joi'
 import { renderVersionBadge } from '../version.js'
-import { BaseJsonService } from '../index.js'
-import { latest, versionColor } from './gem-helpers.js'
+import { BaseJsonService, pathParam, queryParam } from '../index.js'
+import { description, latest, versionColor } from './gem-helpers.js'
 
 const schema = Joi.object({
   // In most cases `version` will be a SemVer but the registry doesn't
@@ -25,23 +25,25 @@ const queryParamSchema = Joi.object({
 export default class GemVersion extends BaseJsonService {
   static category = 'version'
   static route = { base: 'gem/v', pattern: ':gem', queryParamSchema }
-  static examples = [
-    {
-      title: 'Gem',
-      namedParams: { gem: 'formatador' },
-      staticPreview: this.render({ version: '2.1.0' }),
-      keywords: ['ruby'],
-    },
-    {
-      title: 'Gem (including prereleases)',
-      namedParams: { gem: 'flame' },
-      queryParams: {
-        include_prereleases: null,
+  static openApi = {
+    '/gem/v/{gem}': {
+      get: {
+        summary: 'Gem Version',
+        description,
+        parameters: [
+          pathParam({
+            name: 'gem',
+            example: 'formatador',
+          }),
+          queryParam({
+            name: 'include_prereleases',
+            schema: { type: 'boolean' },
+            example: null,
+          }),
+        ],
       },
-      staticPreview: this.render({ version: '5.0.0.rc6' }),
-      keywords: ['ruby'],
     },
-  ]
+  }
 
   static defaultBadgeData = { label: 'gem' }
 

services/github/github-checks-status.service.js

@@ -1,4 +1,5 @@
 import Joi from 'joi'
+import { pathParams } from '../index.js'
 import { isBuildStatus, renderBuildStatusBadge } from '../build-status.js'
 import { GithubAuthV3Service } from './github-auth-service.js'
 import { documentation, httpErrorsFor } from './github-helpers.js'
@@ -14,47 +15,28 @@ export default class GithubChecksStatus extends GithubAuthV3Service {
     pattern: ':user/:repo/:ref',
   }
 
-  static examples = [
-    {
-      title: 'GitHub branch checks state',
-      namedParams: {
-        user: 'badges',
-        repo: 'shields',
-        ref: 'master',
+  static openApi = {
+    '/github/checks-status/{user}/{repo}/{ref}': {
+      get: {
+        summary: 'GitHub tag checks state',
+        description: documentation,
+        parameters: pathParams(
+          {
+            name: 'user',
+            example: 'badges',
+          },
+          {
+            name: 'repo',
+            example: 'shields',
+          },
+          {
+            name: 'ref',
+            example: '3.3.0',
+          },
+        ),
       },
-      staticPreview: renderBuildStatusBadge({
-        status: 'success',
-      }),
-      keywords: ['status'],
-      documentation,
     },
-    {
-      title: 'GitHub commit checks state',
-      namedParams: {
-        user: 'badges',
-        repo: 'shields',
-        ref: '91b108d4b7359b2f8794a4614c11cb1157dc9fff',
-      },
-      staticPreview: renderBuildStatusBadge({
-        status: 'success',
-      }),
-      keywords: ['status'],
-      documentation,
-    },
-    {
-      title: 'GitHub tag checks state',
-      namedParams: {
-        user: 'badges',
-        repo: 'shields',
-        ref: '3.3.0',
-      },
-      staticPreview: renderBuildStatusBadge({
-        status: 'success',
-      }),
-      keywords: ['status'],
-      documentation,
-    },
-  ]
+  }
 
   static defaultBadgeData = { label: 'checks' }
 

services/github/github-lerna-json.service.js

@@ -1,4 +1,5 @@
 import Joi from 'joi'
+import { pathParams } from '../index.js'
 import { renderVersionBadge } from '../version.js'
 import { semver } from '../validators.js'
 import { ConditionalGithubAuthV3Service } from './github-auth-service.js'
@@ -16,25 +17,44 @@ export default class GithubLernaJson extends ConditionalGithubAuthV3Service {
     pattern: ':user/:repo/:branch*',
   }
 
-  static examples = [
-    {
-      title: 'Github lerna version',
-      pattern: ':user/:repo',
-      namedParams: { user: 'babel', repo: 'babel' },
-      staticPreview: this.render({ version: '7.6.4' }),
-      documentation,
+  static openApi = {
+    '/github/lerna-json/v/{user}/{repo}': {
+      get: {
+        summary: 'Github lerna version',
+        description: documentation,
+        parameters: pathParams(
+          {
+            name: 'user',
+            example: 'babel',
+          },
+          {
+            name: 'repo',
+            example: 'babel',
+          },
+        ),
+      },
     },
-    {
-      title: 'Github lerna version (branch)',
-      pattern: ':user/:repo/:branch',
-      namedParams: { user: 'jneander', repo: 'jneander', branch: 'colors' },
-      staticPreview: this.render({
-        version: 'independent',
-        branch: 'colors',
-      }),
-      documentation,
+    '/github/lerna-json/v/{user}/{repo}/{branch}': {
+      get: {
+        summary: 'Github lerna version (branch)',
+        description: documentation,
+        parameters: pathParams(
+          {
+            name: 'user',
+            example: 'jneander',
+          },
+          {
+            name: 'repo',
+            example: 'jneander',
+          },
+          {
+            name: 'branch',
+            example: 'colors',
+          },
+        ),
+      },
     },
-  ]
+  }
 
   static defaultBadgeData = { label: 'lerna' }
 

services/github/github-pull-request-check-state.service.js

@@ -1,5 +1,6 @@
 import Joi from 'joi'
 import countBy from 'lodash.countby'
+import { pathParams } from '../index.js'
 import { GithubAuthV3Service } from './github-auth-service.js'
 import { fetchIssue } from './github-common-fetch.js'
 import { documentation, httpErrorsFor } from './github-helpers.js'
@@ -15,8 +16,6 @@ const schema = Joi.object({
     .default([]),
 }).required()
 
-const keywords = ['pullrequest', 'detail']
-
 export default class GithubPullRequestCheckState extends GithubAuthV3Service {
   static category = 'build'
   static route = {
@@ -24,36 +23,48 @@ export default class GithubPullRequestCheckState extends GithubAuthV3Service {
     pattern: ':variant(s|contexts)/pulls/:user/:repo/:number(\\d+)',
   }
 
-  static examples = [
-    {
-      title: 'GitHub pull request check state',
-      pattern: 's/pulls/:user/:repo/:number',
-      namedParams: {
-        user: 'badges',
-        repo: 'shields',
-        number: '1110',
+  static openApi = {
+    '/github/status/s/pulls/{user}/{repo}/{number}': {
+      get: {
+        summary: 'GitHub pull request check state',
+        description: documentation,
+        parameters: pathParams(
+          {
+            name: 'user',
+            example: 'badges',
+          },
+          {
+            name: 'repo',
+            example: 'shields',
+          },
+          {
+            name: 'number',
+            example: '1110',
+          },
+        ),
       },
-      staticPreview: this.render({ variant: 's', state: 'pending' }),
-      keywords,
-      documentation,
     },
-    {
-      title: 'GitHub pull request check contexts',
-      pattern: 'contexts/pulls/:user/:repo/:number',
-      namedParams: {
-        user: 'badges',
-        repo: 'shields',
-        number: '1110',
+    '/github/status/contexts/pulls/{user}/{repo}/{number}': {
+      get: {
+        summary: 'GitHub pull request check contexts',
+        description: documentation,
+        parameters: pathParams(
+          {
+            name: 'user',
+            example: 'badges',
+          },
+          {
+            name: 'repo',
+            example: 'shields',
+          },
+          {
+            name: 'number',
+            example: '1110',
+          },
+        ),
       },
-      staticPreview: this.render({
-        variant: 'contexts',
-        state: 'pending',
-        stateCounts: { passed: 5, pending: 1 },
-      }),
-      keywords,
-      documentation,
     },
-  ]
+  }
 
   static defaultBadgeData = { label: 'checks', namedLogo: 'github' }
 

services/open-vsx/open-vsx-base.js

@@ -16,13 +16,6 @@ const extensionQuerySchema = Joi.object({
 }).required()
 
 export default class OpenVSXBase extends BaseJsonService {
-  static keywords = [
-    'ovsx',
-    'open-vsx',
-    'ovsx-marketplace',
-    'open-vsx-marketplace',
-  ]
-
   static defaultBadgeData = {
     label: 'open vsx',
     color: 'blue',
@@ -41,3 +34,8 @@ export default class OpenVSXBase extends BaseJsonService {
     })
   }
 }
+
+const description =
+  '[Open VSX](https://open-vsx.org/) (OVSX) is a registry of extensions for VS Code compatible editors.'
+
+export { OpenVSXBase, description }

services/open-vsx/open-vsx-downloads.service.js

@@ -1,5 +1,6 @@
+import { pathParams } from '../index.js'
 import { renderDownloadsBadge } from '../downloads.js'
-import OpenVSXBase from './open-vsx-base.js'
+import { OpenVSXBase, description } from './open-vsx-base.js'
 
 export default class OpenVSXDownloads extends OpenVSXBase {
   static category = 'downloads'
@@ -9,32 +10,44 @@ export default class OpenVSXDownloads extends OpenVSXBase {
     pattern: ':interval(dt)/:namespace/:extension/:version*',
   }
 
-  static examples = [
-    {
-      title: 'Open VSX Downloads',
-      pattern: 'dt/:namespace/:extension',
-      namedParams: {
-        namespace: 'redhat',
-        extension: 'java',
+  static openApi = {
+    '/open-vsx/dt/{namespace}/{extension}': {
+      get: {
+        summary: 'Open VSX Downloads',
+        description,
+        parameters: pathParams(
+          {
+            name: 'namespace',
+            example: 'redhat',
+          },
+          {
+            name: 'extension',
+            example: 'java',
+          },
+        ),
       },
-      staticPreview: renderDownloadsBadge({ downloads: 29000 }),
-      keywords: this.keywords,
     },
-    {
-      title: 'Open VSX Downloads (version)',
-      pattern: 'dt/:namespace/:extension/:version',
-      namedParams: {
-        namespace: 'redhat',
-        extension: 'java',
-        version: '0.69.0',
+    '/open-vsx/dt/{namespace}/{extension}/{version}': {
+      get: {
+        summary: 'Open VSX Downloads (version)',
+        description,
+        parameters: pathParams(
+          {
+            name: 'namespace',
+            example: 'redhat',
+          },
+          {
+            name: 'extension',
+            example: 'java',
+          },
+          {
+            name: 'version',
+            example: '0.69.0',
+          },
+        ),
       },
-      staticPreview: renderDownloadsBadge({
-        version: '0.69.0',
-        downloads: 29000,
-      }),
-      keywords: this.keywords,
     },
-  ]
+  }
 
   static defaultBadgeData = { label: 'downloads' }
 

services/open-vsx/open-vsx-rating.service.js

@@ -1,6 +1,7 @@
+import { pathParams } from '../index.js'
 import { starRating } from '../text-formatters.js'
 import { floorCount } from '../color-formatters.js'
-import OpenVSXBase from './open-vsx-base.js'
+import { OpenVSXBase, description } from './open-vsx-base.js'
 
 export default class OpenVSXRating extends OpenVSXBase {
   static category = 'rating'
@@ -10,36 +11,29 @@ export default class OpenVSXRating extends OpenVSXBase {
     pattern: ':format(rating|stars)/:namespace/:extension',
   }
 
-  static examples = [
-    {
-      title: 'Open VSX Rating',
-      pattern: 'rating/:namespace/:extension',
-      namedParams: {
-        namespace: 'redhat',
-        extension: 'java',
+  static openApi = {
+    '/open-vsx/{format}/{namespace}/{extension}': {
+      get: {
+        summary: 'Open VSX Rating',
+        description,
+        parameters: pathParams(
+          {
+            name: 'format',
+            example: 'rating',
+            schema: { type: 'string', enum: this.getEnum('format') },
+          },
+          {
+            name: 'namespace',
+            example: 'redhat',
+          },
+          {
+            name: 'extension',
+            example: 'java',
+          },
+        ),
       },
-      staticPreview: this.render({
-        format: 'rating',
-        averageRating: 5,
-        ratingCount: 2,
-      }),
-      keywords: this.keywords,
     },
-    {
-      title: 'Open VSX Rating (Stars)',
-      pattern: 'stars/:namespace/:extension',
-      namedParams: {
-        namespace: 'redhat',
-        extension: 'java',
-      },
-      staticPreview: this.render({
-        format: 'stars',
-        averageRating: 5,
-        ratingCount: 2,
-      }),
-      keywords: this.keywords,
-    },
-  ]
+  }
 
   static defaultBadgeData = {
     label: 'rating',

services/open-vsx/open-vsx-release-date.service.js

@@ -1,7 +1,7 @@
 import { pathParams } from '../index.js'
 import { age } from '../color-formatters.js'
 import { formatDate } from '../text-formatters.js'
-import OpenVSXBase from './open-vsx-base.js'
+import { OpenVSXBase, description } from './open-vsx-base.js'
 
 export default class OpenVSXReleaseDate extends OpenVSXBase {
   static category = 'activity'
@@ -15,6 +15,7 @@ export default class OpenVSXReleaseDate extends OpenVSXBase {
     '/open-vsx/release-date/{namespace}/{extension}': {
       get: {
         summary: 'Open VSX Release Date',
+        description,
         parameters: pathParams(
           {
             name: 'namespace',

services/open-vsx/open-vsx-version.service.js

@@ -1,6 +1,6 @@
 import { pathParams } from '../index.js'
 import { renderVersionBadge } from '../version.js'
-import OpenVSXBase from './open-vsx-base.js'
+import { OpenVSXBase, description } from './open-vsx-base.js'
 
 export default class OpenVSXVersion extends OpenVSXBase {
   static category = 'version'
@@ -14,6 +14,7 @@ export default class OpenVSXVersion extends OpenVSXBase {
     '/open-vsx/v/{namespace}/{extension}': {
       get: {
         summary: 'Open VSX Version',
+        description,
         parameters: pathParams(
           {
             name: 'namespace',

services/readthedocs/readthedocs.service.js

@@ -1,8 +1,6 @@
 import Joi from 'joi'
 import { isBuildStatus, renderBuildStatusBadge } from '../build-status.js'
-import { BaseSvgScrapingService, NotFound } from '../index.js'
-
-const keywords = ['documentation']
+import { BaseSvgScrapingService, NotFound, pathParams } from '../index.js'
 
 const schema = Joi.object({
   message: Joi.alternatives()
@@ -10,6 +8,9 @@ const schema = Joi.object({
     .required(),
 }).required()
 
+const description =
+  '[ReadTheDocs](https://readthedocs.com/) is a hosting service for documentation.'
+
 export default class ReadTheDocs extends BaseSvgScrapingService {
   static category = 'build'
 
@@ -18,22 +19,34 @@ export default class ReadTheDocs extends BaseSvgScrapingService {
     pattern: ':project/:version?',
   }
 
-  static examples = [
-    {
-      title: 'Read the Docs',
-      pattern: ':packageName',
-      namedParams: { packageName: 'pip' },
-      staticPreview: this.render({ status: 'passing' }),
-      keywords,
+  static openApi = {
+    '/readthedocs/{packageName}': {
+      get: {
+        summary: 'Read the Docs',
+        description,
+        parameters: pathParams({
+          name: 'packageName',
+          example: 'pip',
+        }),
+      },
     },
-    {
-      title: 'Read the Docs (version)',
-      pattern: ':packageName/:version',
-      namedParams: { packageName: 'pip', version: 'stable' },
-      staticPreview: this.render({ status: 'passing' }),
-      keywords,
+    '/readthedocs/{packageName}/{version}': {
+      get: {
+        summary: 'Read the Docs (version)',
+        description,
+        parameters: pathParams(
+          {
+            name: 'packageName',
+            example: 'pip',
+          },
+          {
+            name: 'version',
+            example: 'stable',
+          },
+        ),
+      },
     },
-  ]
+  }
 
   static defaultBadgeData = {
     label: 'docs',