migrate some services from examples to openApi part 28; affects [aur cran mastodon matrix npmstat nyc thunderstore twitter] (#9855)

* migrate some services from examples to openApi

* always use capitals in period/interval description

services/aur/aur.service.js

@@ -6,7 +6,12 @@ import {
 import { renderLicenseBadge } from '../licenses.js'
 import { addv, metric, formatDate } from '../text-formatters.js'
 import { nonNegativeInteger } from '../validators.js'
-import { BaseJsonService, NotFound, InvalidResponse } from '../index.js'
+import {
+  BaseJsonService,
+  NotFound,
+  InvalidResponse,
+  pathParams,
+} from '../index.js'
 
 const aurSchema = Joi.object({
   resultcount: nonNegativeInteger,
@@ -52,13 +57,18 @@ class AurLicense extends BaseAurService {
   static category = 'license'
   static route = { base: 'aur/license', pattern: ':packageName' }
 
-  static examples = [
-    {
-      title: 'AUR license',
-      namedParams: { packageName: 'android-studio' },
-      staticPreview: renderLicenseBadge({ license: 'Apache', color: 'blue' }),
+  static openApi = {
+    '/aur/license/{packageName}': {
+      get: {
+        summary: 'AUR License',
+        description: 'Arch linux User Repository License',
+        parameters: pathParams({
+          name: 'packageName',
+          example: 'android-studio',
+        }),
+      },
     },
-  ]
+  }
 
   static defaultBadgeData = { label: 'license' }
 
@@ -83,13 +93,15 @@ class AurVotes extends BaseAurService {
 
   static route = { base: 'aur/votes', pattern: ':packageName' }
 
-  static examples = [
-    {
-      title: 'AUR votes',
-      namedParams: { packageName: 'dropbox' },
-      staticPreview: this.render({ votes: '2280' }),
+  static openApi = {
+    '/aur/votes/{packageName}': {
+      get: {
+        summary: 'AUR Votes',
+        description: 'Arch linux User Repository Votes',
+        parameters: pathParams({ name: 'packageName', example: 'dropbox' }),
+      },
     },
-  ]
+  }
 
   static defaultBadgeData = { label: 'votes' }
 
@@ -109,13 +121,19 @@ class AurVotes extends BaseAurService {
 class AurVersion extends BaseAurService {
   static category = 'version'
   static route = { base: 'aur/version', pattern: ':packageName' }
-  static examples = [
-    {
-      title: 'AUR version',
-      namedParams: { packageName: 'visual-studio-code-bin' },
-      staticPreview: this.render({ version: '1.34.0-2', outOfDate: null }),
+
+  static openApi = {
+    '/aur/version/{packageName}': {
+      get: {
+        summary: 'AUR Version',
+        description: 'Arch linux User Repository Version',
+        parameters: pathParams({
+          name: 'packageName',
+          example: 'visual-studio-code-bin',
+        }),
+      },
     },
-  ]
+  }
 
   static _cacheLength = 3600
 
@@ -140,13 +158,18 @@ class AurMaintainer extends BaseAurService {
 
   static route = { base: 'aur/maintainer', pattern: ':packageName' }
 
-  static examples = [
-    {
-      title: 'AUR maintainer',
-      namedParams: { packageName: 'google-chrome' },
-      staticPreview: this.render({ maintainer: 'luzifer' }),
+  static openApi = {
+    '/aur/maintainer/{packageName}': {
+      get: {
+        summary: 'AUR Maintainer',
+        description: 'Arch linux User Repository Maintainer',
+        parameters: pathParams({
+          name: 'packageName',
+          example: 'google-chrome',
+        }),
+      },
     },
-  ]
+  }
 
   static defaultBadgeData = { label: 'maintainer', color: 'blue' }
 
@@ -173,13 +196,18 @@ class AurLastModified extends BaseAurService {
     pattern: ':packageName',
   }
 
-  static examples = [
-    {
-      title: 'AUR last modified',
-      namedParams: { packageName: 'google-chrome' },
-      staticPreview: this.render({ date: new Date().getTime() }),
+  static openApi = {
+    '/aur/last-modified/{packageName}': {
+      get: {
+        summary: 'AUR Last Modified',
+        description: 'Arch linux User Repository Last Modified',
+        parameters: pathParams({
+          name: 'packageName',
+          example: 'google-chrome',
+        }),
+      },
     },
-  ]
+  }
 
   static defaultBadgeData = { label: 'last modified' }
 

services/cran/cran.service.js

@@ -1,6 +1,6 @@
 import Joi from 'joi'
 import { renderVersionBadge } from '../version.js'
-import { BaseJsonService } from '../index.js'
+import { BaseJsonService, pathParams } from '../index.js'
 
 const schema = Joi.object({
   License: Joi.string().required(),
@@ -20,13 +20,17 @@ class CranLicense extends BaseCranService {
   static category = 'license'
   static route = { base: 'cran/l', pattern: ':packageName' }
 
-  static examples = [
-    {
-      title: 'CRAN/METACRAN',
-      namedParams: { packageName: 'devtools' },
-      staticPreview: this.render({ license: 'MIT + file LICENSE' }),
+  static openApi = {
+    '/cran/l/{packageName}': {
+      get: {
+        summary: 'CRAN/METACRAN License',
+        parameters: pathParams({
+          name: 'packageName',
+          example: 'devtools',
+        }),
+      },
     },
-  ]
+  }
 
   static render({ license }) {
     return {
@@ -46,13 +50,17 @@ class CranVersion extends BaseCranService {
   static category = 'version'
   static route = { base: 'cran/v', pattern: ':packageName' }
 
-  static examples = [
-    {
-      title: 'CRAN/METACRAN',
-      namedParams: { packageName: 'devtools' },
-      staticPreview: this.render({ version: '2.0.1' }),
+  static openApi = {
+    '/cran/v/{packageName}': {
+      get: {
+        summary: 'CRAN/METACRAN Version',
+        parameters: pathParams({
+          name: 'packageName',
+          example: 'devtools',
+        }),
+      },
     },
-  ]
+  }
 
   static render({ version }) {
     return renderVersionBadge({ version })

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

@@ -16,7 +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',
+            description: 'Hits per Day, Week, Month or Year',
           },
           {
             name: 'user',

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

@@ -16,7 +16,7 @@ export default class JsDelivrHitsNPM extends BaseJsDelivrService {
             name: 'period',
             schema: { type: 'string', enum: this.getEnum('period') },
             example: 'hm',
-            description: 'Hits per day, week, month or year',
+            description: 'Hits per Day, Week, Month or Year',
           },
           {
             name: 'packageName',
@@ -33,7 +33,7 @@ export default class JsDelivrHitsNPM extends BaseJsDelivrService {
             name: 'period',
             schema: { type: 'string', enum: this.getEnum('period') },
             example: 'hm',
-            description: 'Hits per day, week, month or year',
+            description: 'Hits per Day, Week, Month or Year',
           },
           {
             name: 'scope',

services/mastodon/mastodon-follow.service.js

@@ -1,7 +1,7 @@
 import Joi from 'joi'
 import { metric } from '../text-formatters.js'
 import { optionalUrl, nonNegativeInteger } from '../validators.js'
-import { BaseJsonService, NotFound } from '../index.js'
+import { BaseJsonService, NotFound, pathParam, queryParam } from '../index.js'
 
 const schema = Joi.object({
   username: Joi.string().required(),
@@ -12,7 +12,7 @@ const queryParamSchema = Joi.object({
   domain: optionalUrl,
 }).required()
 
-const documentation = `
+const description = `
 To find your user id, you can use [this tool](https://prouser123.me/misc/mastodon-userid-lookup.html).
 
 Alternatively you can make a request to \`https://your.mastodon.server/.well-known/webfinger?resource=acct:<user>@<domain>\`
@@ -29,21 +29,24 @@ export default class MastodonFollow extends BaseJsonService {
     queryParamSchema,
   }
 
-  static examples = [
-    {
-      title: 'Mastodon Follow',
-      namedParams: {
-        id: '26471',
+  static openApi = {
+    '/mastodon/follow/{id}': {
+      get: {
+        summary: 'Mastodon Follow',
+        description,
+        parameters: [
+          pathParam({
+            name: 'id',
+            example: '26471',
+          }),
+          queryParam({
+            name: 'domain',
+            example: 'https://mastodon.social',
+          }),
+        ],
       },
-      queryParams: { domain: 'https://mastodon.social' },
-      staticPreview: {
-        label: 'Follow',
-        message: '862',
-        style: 'social',
-      },
-      documentation,
     },
-  ]
+  }
 
   static defaultBadgeData = {
     namedLogo: 'mastodon',

services/matrix/matrix.service.js

@@ -1,5 +1,10 @@
 import Joi from 'joi'
-import { BaseJsonService, InvalidParameter } from '../index.js'
+import {
+  BaseJsonService,
+  InvalidParameter,
+  pathParam,
+  queryParam,
+} from '../index.js'
 
 const queryParamSchema = Joi.object({
   server_fqdn: Joi.string().hostname(),
@@ -26,12 +31,12 @@ const matrixStateSchema = Joi.array()
   )
   .required()
 
-const documentation = `
+const description = `
   <p>
     In order for this badge to work, the host of your room must allow guest accounts or dummy accounts to register, and the room must be world readable (chat history visible to anyone).
-    <br>
+    <br />
     The following steps will show you how to setup the badge URL using the Element Matrix client.
-    <br>
+    <br />
     <ul>
       <li>Select the desired room inside the Element client</li>
       <li>Click on the room settings button (gear icon) located near the top right of the client</li>
@@ -41,11 +46,11 @@ const documentation = `
       <li>Remove the starting hash character (<code>#</code>)</li>
       <li>The final badge URL should look something like this <code>/matrix/twim:matrix.org.svg</code></li>
     </ul>
-    <br>
+    <br />
     Some Matrix homeservers don't hold a server name matching where they live (e.g. if the homeserver <code>example.com</code> that created the room alias <code>#mysuperroom:example.com</code> lives at <code>matrix.example.com</code>).
-    <br>
+    <br />
     If that is the case of the homeserver that created the room alias used for generating the badge, you will need to add the server's FQDN (fully qualified domain name) as a query parameter.
-    <br>
+    <br />
     The final badge URL should then look something like this <code>/matrix/mysuperroom:example.com.svg?server_fqdn=matrix.example.com</code>.
   </p>
   `
@@ -59,21 +64,24 @@ export default class Matrix extends BaseJsonService {
     queryParamSchema,
   }
 
-  static examples = [
-    {
-      title: 'Matrix',
-      namedParams: { roomAlias: 'twim:matrix.org' },
-      staticPreview: this.render({ members: 42 }),
-      documentation,
+  static openApi = {
+    '/matrix/{roomAlias}': {
+      get: {
+        summary: 'Matrix',
+        description,
+        parameters: [
+          pathParam({
+            name: 'roomAlias',
+            example: 'twim:matrix.org',
+          }),
+          queryParam({
+            name: 'server_fqdn',
+            example: 'matrix.org',
+          }),
+        ],
+      },
     },
-    {
-      title: 'Matrix',
-      namedParams: { roomAlias: 'twim:matrix.org' },
-      queryParams: { server_fqdn: 'matrix.org' },
-      staticPreview: this.render({ members: 42 }),
-      documentation,
-    },
-  ]
+  }
 
   static _cacheLength = 30
 

services/npm-stat/npm-stat-downloads.service.js

@@ -1,7 +1,7 @@
 import Joi from 'joi'
 import dayjs from 'dayjs'
 import { nonNegativeInteger } from '../validators.js'
-import { BaseJsonService } from '../index.js'
+import { BaseJsonService, pathParams } from '../index.js'
 import { renderDownloadsBadge } from '../downloads.js'
 
 const schema = Joi.object()
@@ -22,16 +22,27 @@ export default class NpmStatDownloads extends BaseJsonService {
     pattern: ':interval(dw|dm|dy)/:author',
   }
 
-  static examples = [
-    {
-      title: 'npm (by author)',
-      documentation:
-        'The total number of downloads of npm packages published by the specified author from [npm-stat](https://npm-stat.com).',
-      namedParams: { interval: 'dy', author: 'dukeluo' },
-      staticPreview: this.render({ interval: 'dy', downloadCount: 30000 }),
-      keywords: ['node'],
+  static openApi = {
+    '/npm-stat/{interval}/{author}': {
+      get: {
+        summary: 'NPM Downloads by package author',
+        description:
+          'The total number of downloads of npm packages published by the specified author from [npm-stat](https://npm-stat.com).',
+        parameters: pathParams(
+          {
+            name: 'interval',
+            example: 'dw',
+            schema: { type: 'string', enum: this.getEnum('interval') },
+            description: 'Downloads per Week, Month or Year',
+          },
+          {
+            name: 'author',
+            example: 'dukeluo',
+          },
+        ),
+      },
     },
-  ]
+  }
 
   static _cacheLength = 21600
 

services/nycrc/nycrc.service.js

@@ -2,7 +2,13 @@ import Joi from 'joi'
 import { coveragePercentage } from '../color-formatters.js'
 import { ConditionalGithubAuthV3Service } from '../github/github-auth-service.js'
 import { fetchJsonFromRepo } from '../github/github-common-fetch.js'
-import { InvalidParameter, InvalidResponse, NotFound } from '../index.js'
+import {
+  InvalidParameter,
+  InvalidResponse,
+  NotFound,
+  pathParam,
+  queryParam,
+} from '../index.js'
 
 const nycrcSchema = Joi.object({
   branches: Joi.number().min(0).max(100),
@@ -23,7 +29,7 @@ const pkgJSONSchema = Joi.object({
   }).optional(),
 }).required()
 
-const documentation = `
+const description = `
 Create a code coverage badge, based on thresholds stored in a
 [.nycrc config file](https://github.com/istanbuljs/nyc#common-configuration-options)
 on GitHub.
@@ -50,15 +56,24 @@ export default class Nycrc extends ConditionalGithubAuthV3Service {
     }).required(),
   }
 
-  static examples = [
-    {
-      title: 'nycrc config on GitHub',
-      namedParams: { user: 'yargs', repo: 'yargs' },
-      queryParams: { config: '.nycrc', preferredThreshold: 'lines' },
-      staticPreview: this.render({ coverage: 92 }),
-      documentation,
+  static openApi = {
+    '/nycrc/{user}/{repo}': {
+      get: {
+        summary: 'nycrc config on GitHub',
+        description,
+        parameters: [
+          pathParam({ name: 'user', example: 'yargs' }),
+          pathParam({ name: 'repo', example: 'yargs' }),
+          queryParam({ name: 'config', example: '.nycrc' }),
+          queryParam({
+            name: 'preferredThreshold',
+            example: 'lines',
+            schema: { type: 'string', enum: validThresholds },
+          }),
+        ],
+      },
     },
-  ]
+  }
 
   static defaultBadgeData = { label: 'min coverage' }
 

services/thunderstore/thunderstore-base.js

@@ -13,7 +13,7 @@ const packageMetricsSchema = Joi.object({
   rating_score: nonNegativeInteger,
 })
 
-const documentation = `
+const description = `
 <p>
   The Thunderstore badges require a package's <code>namespace</code> and <code>name</code>.
 </p>
@@ -90,4 +90,4 @@ class BaseThunderstoreService extends BaseJsonService {
   }
 }
 
-export { BaseThunderstoreService, documentation }
+export { BaseThunderstoreService, description }

services/thunderstore/thunderstore-downloads.service.js

@@ -1,5 +1,6 @@
 import { renderDownloadsBadge } from '../downloads.js'
-import { BaseThunderstoreService, documentation } from './thunderstore-base.js'
+import { pathParams } from '../index.js'
+import { BaseThunderstoreService, description } from './thunderstore-base.js'
 
 export default class ThunderstoreDownloads extends BaseThunderstoreService {
   static category = 'downloads'
@@ -9,17 +10,18 @@ export default class ThunderstoreDownloads extends BaseThunderstoreService {
     pattern: ':namespace/:packageName',
   }
 
-  static examples = [
-    {
-      title: 'Thunderstore Downloads',
-      namedParams: {
-        namespace: 'notnotnotswipez',
-        packageName: 'MoreCompany',
+  static openApi = {
+    '/thunderstore/dt/{namespace}/{packageName}': {
+      get: {
+        summary: 'Thunderstore Downloads',
+        description,
+        parameters: pathParams(
+          { name: 'namespace', example: 'notnotnotswipez' },
+          { name: 'packageName', example: 'MoreCompany' },
+        ),
       },
-      staticPreview: renderDownloadsBadge({ downloads: 120000 }),
-      documentation,
     },
-  ]
+  }
 
   static defaultBadgeData = {
     label: 'downloads',

services/thunderstore/thunderstore-likes.service.js

@@ -1,5 +1,6 @@
 import { metric } from '../text-formatters.js'
-import { BaseThunderstoreService, documentation } from './thunderstore-base.js'
+import { pathParams } from '../index.js'
+import { BaseThunderstoreService, description } from './thunderstore-base.js'
 
 export default class ThunderstoreLikes extends BaseThunderstoreService {
   static category = 'social'
@@ -9,21 +10,18 @@ export default class ThunderstoreLikes extends BaseThunderstoreService {
     pattern: ':namespace/:packageName',
   }
 
-  static examples = [
-    {
-      title: 'Thunderstore Likes',
-      namedParams: {
-        namespace: 'notnotnotswipez',
-        packageName: 'MoreCompany',
+  static openApi = {
+    '/thunderstore/likes/{namespace}/{packageName}': {
+      get: {
+        summary: 'Thunderstore Likes',
+        description,
+        parameters: pathParams(
+          { name: 'namespace', example: 'notnotnotswipez' },
+          { name: 'packageName', example: 'MoreCompany' },
+        ),
       },
-      staticPreview: {
-        label: 'likes',
-        message: '150',
-        style: 'social',
-      },
-      documentation,
     },
-  ]
+  }
 
   static defaultBadgeData = {
     label: 'likes',

services/thunderstore/thunderstore-version.service.js

@@ -1,5 +1,6 @@
 import { renderVersionBadge } from '../version.js'
-import { BaseThunderstoreService, documentation } from './thunderstore-base.js'
+import { pathParams } from '../index.js'
+import { BaseThunderstoreService, description } from './thunderstore-base.js'
 
 export default class ThunderstoreVersion extends BaseThunderstoreService {
   static category = 'version'
@@ -9,17 +10,18 @@ export default class ThunderstoreVersion extends BaseThunderstoreService {
     pattern: ':namespace/:packageName',
   }
 
-  static examples = [
-    {
-      title: 'Thunderstore Version',
-      namedParams: {
-        namespace: 'notnotnotswipez',
-        packageName: 'MoreCompany',
+  static openApi = {
+    '/thunderstore/v/{namespace}/{packageName}': {
+      get: {
+        summary: 'Thunderstore Version',
+        description,
+        parameters: pathParams(
+          { name: 'namespace', example: 'notnotnotswipez' },
+          { name: 'packageName', example: 'MoreCompany' },
+        ),
       },
-      staticPreview: renderVersionBadge({ version: '1.4.5' }),
-      documentation,
     },
-  ]
+  }
 
   static defaultBadgeData = {
     label: 'thunderstore',

services/twitter/twitter.service.js

@@ -1,6 +1,6 @@
 import Joi from 'joi'
 import { optionalUrl } from '../validators.js'
-import { BaseService, BaseJsonService } from '../index.js'
+import { BaseService, pathParams, queryParams } from '../index.js'
 
 const queryParamSchema = Joi.object({
   url: optionalUrl.required(),
@@ -15,22 +15,18 @@ class TwitterUrl extends BaseService {
     queryParamSchema,
   }
 
-  static examples = [
-    {
-      title: 'X (formerly Twitter) URL',
-      namedParams: {},
-      queryParams: {
-        url: 'https://shields.io',
-      },
-      // hard code the static preview
-      // because link[] is not allowed in examples
-      staticPreview: {
-        label: 'Tweet',
-        message: '',
-        style: 'social',
+  static openApi = {
+    '/twitter/url': {
+      get: {
+        summary: 'X (formerly Twitter) URL',
+        parameters: queryParams({
+          name: 'url',
+          example: 'https://shields.io',
+          required: true,
+        }),
       },
     },
-  ]
+  }
 
   static _cacheLength = 86400
 
@@ -65,7 +61,7 @@ due to how widely used the badge was. See
 https://github.com/badges/shields/issues/8837
 for related discussion.
 */
-class TwitterFollow extends BaseJsonService {
+class TwitterFollow extends BaseService {
   static category = 'social'
 
   static route = {
@@ -73,22 +69,14 @@ class TwitterFollow extends BaseJsonService {
     pattern: ':user',
   }
 
-  static examples = [
-    {
-      title: 'X (formerly Twitter) Follow',
-      namedParams: {
-        user: 'shields_io',
-      },
-      queryParams: { label: 'Follow' },
-      // hard code the static preview
-      // because link[] is not allowed in examples
-      staticPreview: {
-        label: 'Follow @shields_io',
-        message: '',
-        style: 'social',
+  static openApi = {
+    '/twitter/follow/{user}': {
+      get: {
+        summary: 'X (formerly Twitter) Follow',
+        parameters: pathParams({ name: 'user', example: 'shields_io' }),
       },
     },
-  ]
+  }
 
   static _cacheLength = 86400