migrate some services from examples to openApi (#9737)

services/bundlejs/bundlejs-package.service.js

@@ -1,5 +1,5 @@
 import Joi from 'joi'
-import { BaseJsonService } from '../index.js'
+import { BaseJsonService, pathParam, queryParam } from '../index.js'
 
 const schema = Joi.object({
   size: Joi.object({
@@ -11,8 +11,6 @@ const queryParamSchema = Joi.object({
   exports: Joi.string(),
 }).required()
 
-const keywords = ['node', 'bundlejs']
-
 const esbuild =
   '<a href="https://github.com/evanw/esbuild" target="_blank" rel="noopener">esbuild</a>'
 const denoflate =
@@ -20,9 +18,9 @@ const denoflate =
 const bundlejs =
   '<a href="https://bundlejs.com/" target="_blank" rel="noopener">bundlejs</a>'
 
-const documentation = `
+const description = `
 <p>
- View ${esbuild} minified and ${denoflate} gzipped size of a package or selected exports, via ${bundlejs}.
+ View ${esbuild} minified and ${denoflate} gzipped size of a javascript package or selected exports, via ${bundlejs}.
 </p>
 `
 
@@ -35,67 +33,48 @@ export default class BundlejsPackage extends BaseJsonService {
     queryParamSchema,
   }
 
-  static examples = [
-    {
-      title: 'npm package minimized gzipped size',
-      pattern: ':packageName',
-      namedParams: {
-        packageName: 'react',
+  static openApi = {
+    '/bundlejs/size/{packageName}': {
+      get: {
+        summary: 'npm package minimized gzipped size',
+        description,
+        parameters: [
+          pathParam({
+            name: 'packageName',
+            example: 'value-enhancer@3.1.2',
+            description:
+              'This can either be a package name e.g: `value-enhancer`, or a package name and version e.g: `value-enhancer@3.1.2`',
+          }),
+          queryParam({
+            name: 'exports',
+            example: 'isVal,val',
+          }),
+        ],
       },
-      staticPreview: this.render({ size: '2.94 kB' }),
-      keywords,
-      documentation,
     },
-    {
-      title: 'npm package minimized gzipped size (version)',
-      pattern: ':packageName',
-      namedParams: {
-        packageName: 'react@18.2.0',
+    '/bundlejs/size/{scope}/{packageName}': {
+      get: {
+        summary: 'npm package minimized gzipped size (scoped)',
+        description,
+        parameters: [
+          pathParam({
+            name: 'scope',
+            example: '@ngneat',
+          }),
+          pathParam({
+            name: 'packageName',
+            example: 'falso@6.4.0',
+            description:
+              'This can either be a package name e.g: `falso`, or a package name and version e.g: `falso@6.4.0`',
+          }),
+          queryParam({
+            name: 'exports',
+            example: 'randEmail,randFullName',
+          }),
+        ],
       },
-      staticPreview: this.render({ size: '2.94 kB' }),
-      keywords,
-      documentation,
     },
-    {
-      title: 'npm package minimized gzipped size (scoped)',
-      pattern: ':scope/:packageName',
-      namedParams: {
-        scope: '@cycle',
-        packageName: 'rx-run',
-      },
-      staticPreview: this.render({ size: '32.3 kB' }),
-      keywords,
-      documentation,
-    },
-    {
-      title: 'npm package minimized gzipped size (select exports)',
-      pattern: ':packageName',
-      namedParams: {
-        packageName: 'value-enhancer',
-      },
-      queryParams: {
-        exports: 'isVal,val',
-      },
-      staticPreview: this.render({ size: '823 B' }),
-      keywords,
-      documentation,
-    },
-    {
-      title:
-        'npm package minimized gzipped size (scoped version select exports)',
-      pattern: ':scope/:packageName',
-      namedParams: {
-        scope: '@ngneat',
-        packageName: 'falso@6.4.0',
-      },
-      queryParams: {
-        exports: 'randEmail,randFullName',
-      },
-      staticPreview: this.render({ size: '17.8 kB' }),
-      keywords,
-      documentation,
-    },
-  ]
+  }
 
   static defaultBadgeData = { label: 'bundlejs', color: 'informational' }
 

services/cirrus/cirrus.service.js

@@ -1,6 +1,6 @@
 import Joi from 'joi'
 import { isBuildStatus, renderBuildStatusBadge } from '../build-status.js'
-import { BaseJsonService } from '../index.js'
+import { BaseJsonService, pathParam, queryParam } from '../index.js'
 
 const schema = Joi.object({
   subject: Joi.string().required(),
@@ -21,37 +21,31 @@ export default class Cirrus extends BaseJsonService {
     queryParamSchema,
   }
 
-  static examples = [
-    {
-      title: 'Cirrus CI - Base Branch Build Status',
-      namedParams: { user: 'flutter', repo: 'flutter' },
-      pattern: 'github/:user/:repo',
-      staticPreview: this.render({ status: 'passing' }),
+  static openApi = {
+    '/cirrus/github/{user}/{repo}': {
+      get: {
+        summary: 'Cirrus CI - Default Branch Build Status',
+        parameters: [
+          pathParam({ name: 'user', example: 'flutter' }),
+          pathParam({ name: 'repo', example: 'flutter' }),
+          queryParam({ name: 'task', example: 'build_docker' }),
+          queryParam({ name: 'script', example: 'test' }),
+        ],
+      },
     },
-    {
-      title: 'Cirrus CI - Specific Branch Build Status',
-      pattern: 'github/:user/:repo/:branch',
-      namedParams: { user: 'flutter', repo: 'flutter', branch: 'master' },
-      staticPreview: this.render({ status: 'passing' }),
+    '/cirrus/github/{user}/{repo}/{branch}': {
+      get: {
+        summary: 'Cirrus CI - Specific Branch Build Status',
+        parameters: [
+          pathParam({ name: 'user', example: 'flutter' }),
+          pathParam({ name: 'repo', example: 'flutter' }),
+          pathParam({ name: 'branch', example: 'master' }),
+          queryParam({ name: 'task', example: 'build_docker' }),
+          queryParam({ name: 'script', example: 'test' }),
+        ],
+      },
     },
-    {
-      title: 'Cirrus CI - Specific Task Build Status',
-      pattern: 'github/:user/:repo',
-      queryParams: { task: 'build_docker' },
-      namedParams: { user: 'flutter', repo: 'cocoon' },
-      staticPreview: this.render({
-        subject: 'build_docker',
-        status: 'passing',
-      }),
-    },
-    {
-      title: 'Cirrus CI - Task and Script Build Status',
-      pattern: 'github/:user/:repo',
-      queryParams: { task: 'build_docker', script: 'test' },
-      namedParams: { user: 'flutter', repo: 'cocoon' },
-      staticPreview: this.render({ subject: 'test', status: 'passing' }),
-    },
-  ]
+  }
 
   static defaultBadgeData = { label: 'build' }
 

services/factorio-mod-portal/factorio-mod-portal.service.js

@@ -1,5 +1,5 @@
 import Joi from 'joi'
-import { BaseJsonService } from '../index.js'
+import { BaseJsonService, pathParams } from '../index.js'
 import { age } from '../color-formatters.js'
 import { formatDate } from '../text-formatters.js'
 import { nonNegativeInteger } from '../validators.js'
@@ -50,13 +50,17 @@ class FactorioModPortalLatestVersion extends BaseFactorioModPortalService {
     pattern: ':modName',
   }
 
-  static examples = [
-    {
-      title: 'Factorio Mod Portal mod version',
-      namedParams: { modName: 'rso-mod' },
-      staticPreview: this.render({ version: '6.2.20' }),
+  static openApi = {
+    '/factorio-mod-portal/v/{modName}': {
+      get: {
+        summary: 'Factorio Mod Portal mod version',
+        parameters: pathParams({
+          name: 'modName',
+          example: 'rso-mod',
+        }),
+      },
     },
-  ]
+  }
 
   static defaultBadgeData = { label: 'latest version' }
 
@@ -79,13 +83,17 @@ class FactorioModPortalFactorioVersion extends BaseFactorioModPortalService {
     pattern: ':modName',
   }
 
-  static examples = [
-    {
-      title: 'Factorio Mod Portal factorio versions',
-      namedParams: { modName: 'rso-mod' },
-      staticPreview: this.render({ version: '1.1' }),
+  static openApi = {
+    '/factorio-mod-portal/factorio-version/{modName}': {
+      get: {
+        summary: 'Factorio Mod Portal factorio versions',
+        parameters: pathParams({
+          name: 'modName',
+          example: 'rso-mod',
+        }),
+      },
     },
-  ]
+  }
 
   static defaultBadgeData = { label: 'factorio version' }
 
@@ -109,15 +117,17 @@ class FactorioModPortalLastUpdated extends BaseFactorioModPortalService {
     pattern: ':modName',
   }
 
-  static examples = [
-    {
-      title: 'Factorio Mod Portal mod',
-      namedParams: { modName: 'rso-mod' },
-      staticPreview: this.render({
-        lastUpdated: new Date(),
-      }),
+  static openApi = {
+    '/factorio-mod-portal/last-updated/{modName}': {
+      get: {
+        summary: 'Factorio Mod Portal last updated',
+        parameters: pathParams({
+          name: 'modName',
+          example: 'rso-mod',
+        }),
+      },
     },
-  ]
+  }
 
   static defaultBadgeData = { label: 'last updated' }
 
@@ -145,15 +155,17 @@ class FactorioModPortalDownloads extends BaseFactorioModPortalService {
     pattern: ':modName',
   }
 
-  static examples = [
-    {
-      title: 'Factorio Mod Portal mod downloads',
-      namedParams: { modName: 'rso-mod' },
-      staticPreview: this.render({
-        downloads: 1694763,
-      }),
+  static openApi = {
+    '/factorio-mod-portal/dt/{modName}': {
+      get: {
+        summary: 'Factorio Mod Portal downloads',
+        parameters: pathParams({
+          name: 'modName',
+          example: 'rso-mod',
+        }),
+      },
     },
-  ]
+  }
 
   static defaultBadgeData = { label: 'downloads' }
 

services/gerrit/gerrit.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'
 
 const queryParamSchema = Joi.object({
   baseUrl: optionalUrl.required(),
@@ -13,19 +13,24 @@ const schema = Joi.object({
 export default class Gerrit extends BaseJsonService {
   static category = 'issue-tracking'
   static route = { base: 'gerrit', pattern: ':changeId', queryParamSchema }
-  static examples = [
-    {
-      title: 'Gerrit change status',
-      namedParams: {
-        changeId: '1011478',
+  static openApi = {
+    '/gerrit/{changeId}': {
+      get: {
+        summary: 'Gerrit change status',
+        parameters: [
+          pathParam({
+            name: 'changeId',
+            example: '1011478',
+          }),
+          queryParam({
+            name: 'baseUrl',
+            example: 'https://android-review.googlesource.com',
+            required: true,
+          }),
+        ],
       },
-      queryParams: { baseUrl: 'https://android-review.googlesource.com' },
-      staticPreview: this.render({
-        changeId: 1011478,
-        status: 'MERGED',
-      }),
     },
-  ]
+  }
 
   static defaultBadgeData = { label: 'gerrit' }
 

services/wikiapiary/wikiapiary-installs.service.js

@@ -1,8 +1,11 @@
 import Joi from 'joi'
 import { renderDownloadsBadge } from '../downloads.js'
-import { BaseJsonService, NotFound } from '../index.js'
+import { BaseJsonService, NotFound, pathParams } from '../index.js'
 
-const documentation = `
+const description = `
+  <p>
+    <a href="https://wikiapiary.com">WikiApiary</a> holds information about MediaWiki websites.
+  </p>
   <p>
     The name of an extension is case-sensitive excluding the first character.
   </p>
@@ -52,15 +55,22 @@ export default class WikiapiaryInstalls extends BaseJsonService {
     pattern: ':variant(extension|skin|farm|generator|host)/installs/:name',
   }
 
-  static examples = [
-    {
-      title: 'Wikiapiary installs',
-      namedParams: { variant: 'extension', name: 'ParserFunctions' },
-      staticPreview: this.render({ usage: 11170 }),
-      documentation,
-      keywords: ['mediawiki'],
+  static openApi = {
+    '/wikiapiary/{variant}/installs/{name}': {
+      get: {
+        summary: 'Wikiapiary installs',
+        description,
+        parameters: pathParams(
+          {
+            name: 'variant',
+            example: 'extension',
+            schema: { type: 'string', enum: this.getEnum('variant') },
+          },
+          { name: 'name', example: 'ParserFunctions' },
+        ),
+      },
     },
-  ]
+  }
 
   static defaultBadgeData = { label: 'installs', color: 'informational' }