migrate examples to openApi part 13; affects [curseforge date fedora hsts modrinth ore] (#9499)

* migrate some services from examples to openApi

* improve and de-dupe service titles

* improve ore description

services/curseforge/curseforge-base.js

@@ -14,7 +14,7 @@ const schema = Joi.object({
   }).required(),
 }).required()
 
-const documentation = `
+const description = `
 <p>
   The CurseForge badge requires the <code>Project ID</code> in order access the
   <a href="https://docs.curseforge.com/#get-mod" target="_blank">CurseForge API</a>.
@@ -58,4 +58,4 @@ export default class BaseCurseForgeService extends BaseJsonService {
   }
 }
 
-export { BaseCurseForgeService, documentation }
+export { BaseCurseForgeService, description }

services/curseforge/curseforge-downloads.service.js

@@ -1,5 +1,6 @@
+import { pathParams } from '../index.js'
 import { renderDownloadsBadge } from '../downloads.js'
-import BaseCurseForgeService, { documentation } from './curseforge-base.js'
+import BaseCurseForgeService, { description } from './curseforge-base.js'
 
 export default class CurseForgeDownloads extends BaseCurseForgeService {
   static category = 'downloads'
@@ -9,16 +10,18 @@ export default class CurseForgeDownloads extends BaseCurseForgeService {
     pattern: ':projectId',
   }
 
-  static examples = [
+  static openApi = {
-    {
+    '/curseforge/dt/{projectId}': {
-      title: 'CurseForge Downloads',
+      get: {
-      namedParams: {
+        summary: 'CurseForge Downloads',
-        projectId: '238222',
+        description,
+        parameters: pathParams({
+          name: 'projectId',
+          example: '238222',
+        }),
       },
-      staticPreview: renderDownloadsBadge({ downloads: 234000000 }),
-      documentation,
     },
-  ]
+  }
 
   static defaultBadgeData = { label: 'downloads' }
 

services/curseforge/curseforge-game-versions.service.js

@@ -1,4 +1,5 @@
-import BaseCurseForgeService, { documentation } from './curseforge-base.js'
+import { pathParams } from '../index.js'
+import BaseCurseForgeService, { description } from './curseforge-base.js'
 
 export default class CurseForgeGameVersions extends BaseCurseForgeService {
   static category = 'platform-support'
@@ -8,16 +9,18 @@ export default class CurseForgeGameVersions extends BaseCurseForgeService {
     pattern: ':projectId',
   }
 
-  static examples = [
+  static openApi = {
-    {
+    '/curseforge/game-versions/{projectId}': {
-      title: 'CurseForge Game Versions',
+      get: {
-      namedParams: {
+        summary: 'CurseForge Game Versions',
-        projectId: '238222',
+        description,
+        parameters: pathParams({
+          name: 'projectId',
+          example: '238222',
+        }),
       },
-      staticPreview: this.render({ versions: ['1.20.0', '1.19.4'] }),
-      documentation,
     },
-  ]
+  }
 
   static defaultBadgeData = { label: 'game versions' }
 

services/curseforge/curseforge-version.service.js

@@ -1,5 +1,6 @@
+import { pathParams } from '../index.js'
 import { renderVersionBadge } from '../version.js'
-import BaseCurseForgeService, { documentation } from './curseforge-base.js'
+import BaseCurseForgeService, { description } from './curseforge-base.js'
 
 export default class CurseForgeVersion extends BaseCurseForgeService {
   static category = 'version'
@@ -9,18 +10,18 @@ export default class CurseForgeVersion extends BaseCurseForgeService {
     pattern: ':projectId',
   }
 
-  static examples = [
+  static openApi = {
-    {
+    '/curseforge/v/{projectId}': {
-      title: 'CurseForge Version',
+      get: {
-      namedParams: {
+        summary: 'CurseForge Version',
-        projectId: '238222',
+        description,
+        parameters: pathParams({
+          name: 'projectId',
+          example: '238222',
+        }),
       },
-      staticPreview: renderVersionBadge({
-        version: 'jei-1.20-forge-14.0.0.4.jar',
-      }),
-      documentation,
     },
-  ]
+  }
 
   static defaultBadgeData = { label: 'version' }
 

services/date/date.service.js

@@ -1,7 +1,7 @@
 import { formatRelativeDate } from '../text-formatters.js'
-import { BaseService } from '../index.js'
+import { BaseService, pathParams } from '../index.js'
 
-const documentation = `
+const description = `
 <p>
   Supply a unix timestamp in seconds to display the relative time from/to now
 </p>
@@ -11,16 +11,18 @@ export default class Date extends BaseService {
   static category = 'other'
   static route = { base: 'date', pattern: ':timestamp(-?[0-9]+)' }
 
-  static examples = [
+  static openApi = {
-    {
+    '/date/{timestamp}': {
-      title: 'Relative date',
+      get: {
-      pattern: ':timestamp',
+        summary: 'Relative date',
-      namedParams: { timestamp: '1540814400' },
+        description,
-      staticPreview: this.render({ relativeDateString: '2 days ago' }),
+        parameters: pathParams({
-      keywords: ['time', 'countdown', 'countup', 'moment'],
+          name: 'timestamp',
-      documentation,
+          example: '1540814400',
+        }),
+      },
     },
-  ]
+  }
 
   static defaultBadgeData = { label: 'date' }
 

services/fedora/fedora.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({
   version: Joi.string().required(),
@@ -9,18 +9,40 @@ const schema = Joi.object({
 // No way to permalink to current "stable", https://pagure.io/mdapi/issue/69
 const defaultBranch = 'rawhide'
 
+const description =
+  'See <a href="https://apps.fedoraproject.org/mdapi/">mdapi docs</a> for information on valid branches.'
+
 export default class Fedora extends BaseJsonService {
   static category = 'version'
   static route = { base: 'fedora/v', pattern: ':packageName/:branch?' }
-  static examples = [
+  static openApi = {
-    {
+    '/fedora/v/{packageName}/{branch}': {
-      title: 'Fedora package',
+      get: {
-      namedParams: { packageName: 'rpm', branch: 'rawhide' },
+        summary: 'Fedora package (with branch)',
-      staticPreview: renderVersionBadge({ version: '4.14.2.1' }),
+        description,
-      documentation:
+        parameters: pathParams(
-        'See <a href="https://apps.fedoraproject.org/mdapi/">mdapi docs</a> for information on valid branches.',
+          {
+            name: 'packageName',
+            example: 'rpm',
+          },
+          {
+            name: 'branch',
+            example: 'rawhide',
+          },
+        ),
+      },
     },
-  ]
+    '/fedora/v/{packageName}': {
+      get: {
+        summary: 'Fedora package',
+        description,
+        parameters: pathParams({
+          name: 'packageName',
+          example: 'rpm',
+        }),
+      },
+    },
+  }
 
   static defaultBadgeData = { label: 'fedora' }
 

services/hsts/hsts.service.js

@@ -1,11 +1,12 @@
 import Joi from 'joi'
-import { BaseJsonService } from '../index.js'
+import { BaseJsonService, pathParams } from '../index.js'
+
 const label = 'hsts preloaded'
 const schema = Joi.object({
   status: Joi.string().required(),
 }).required()
 
-const documentation = `
+const description = `
 [\`Strict-Transport-Security\` is an HTTP response header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Strict-Transport-Security)
 that signals that browsers should only access the site using HTTPS.
 
@@ -24,15 +25,18 @@ export default class HSTS extends BaseJsonService {
     pattern: ':domain',
   }
 
-  static examples = [
+  static openApi = {
-    {
+    '/hsts/preload/{domain}': {
-      title: 'Chromium HSTS preload',
+      get: {
-      namedParams: { domain: 'github.com' },
+        summary: 'Chromium HSTS preload',
-      staticPreview: this.render({ status: 'preloaded' }),
+        description,
-      keywords: ['security'],
+        parameters: pathParams({
-      documentation,
+          name: 'domain',
+          example: 'github.com',
+        }),
+      },
     },
-  ]
+  }
 
   static render({ status }) {
     let color = 'red'

services/modrinth/modrinth-base.js

@@ -16,7 +16,7 @@ const versionSchema = Joi.array()
   )
   .required()
 
-const documentation =
+const description =
   "<p>You can use your project slug, or the project ID. The ID can be found in the 'Technical information' section of your Modrinth page.</p>"
 
 class BaseModrinthService extends BaseJsonService {
@@ -36,4 +36,4 @@ class BaseModrinthService extends BaseJsonService {
   }
 }
 
-export { BaseModrinthService, documentation }
+export { BaseModrinthService, description }

services/modrinth/modrinth-downloads.service.js

@@ -1,5 +1,6 @@
+import { pathParams } from '../index.js'
 import { renderDownloadsBadge } from '../downloads.js'
-import { BaseModrinthService, documentation } from './modrinth-base.js'
+import { BaseModrinthService, description } from './modrinth-base.js'
 
 export default class ModrinthDownloads extends BaseModrinthService {
   static category = 'downloads'
@@ -9,14 +10,18 @@ export default class ModrinthDownloads extends BaseModrinthService {
     pattern: ':projectId',
   }
 
-  static examples = [
+  static openApi = {
-    {
+    '/modrinth/dt/{projectId}': {
-      title: 'Modrinth Downloads',
+      get: {
-      namedParams: { projectId: 'AANobbMI' },
+        summary: 'Modrinth Downloads',
-      staticPreview: renderDownloadsBadge({ downloads: 120000 }),
+        description,
-      documentation,
+        parameters: pathParams({
+          name: 'projectId',
+          example: 'AANobbMI',
+        }),
+      },
     },
-  ]
+  }
 
   static defaultBadgeData = { label: 'downloads' }
 

services/modrinth/modrinth-followers.service.js

@@ -1,5 +1,6 @@
+import { pathParams } from '../index.js'
 import { metric } from '../text-formatters.js'
-import { BaseModrinthService, documentation } from './modrinth-base.js'
+import { BaseModrinthService, description } from './modrinth-base.js'
 
 export default class ModrinthFollowers extends BaseModrinthService {
   static category = 'social'
@@ -9,17 +10,18 @@ export default class ModrinthFollowers extends BaseModrinthService {
     pattern: ':projectId',
   }
 
-  static examples = [
+  static openApi = {
-    {
+    '/modrinth/followers/{projectId}': {
-      title: 'Modrinth Followers',
+      get: {
-      namedParams: { projectId: 'AANobbMI' },
+        summary: 'Modrinth Followers',
-      staticPreview: Object.assign(this.render({ followers: 176 }), {
+        description,
-        label: 'Followers',
+        parameters: pathParams({
-        style: 'social',
+          name: 'projectId',
-      }),
+          example: 'AANobbMI',
-      documentation,
+        }),
+      },
     },
-  ]
+  }
 
   static defaultBadgeData = { label: 'followers' }
 

services/modrinth/modrinth-game-versions.service.js

@@ -1,4 +1,5 @@
-import { BaseModrinthService, documentation } from './modrinth-base.js'
+import { pathParams } from '../index.js'
+import { BaseModrinthService, description } from './modrinth-base.js'
 
 export default class ModrinthGameVersions extends BaseModrinthService {
   static category = 'platform-support'
@@ -8,14 +9,18 @@ export default class ModrinthGameVersions extends BaseModrinthService {
     pattern: ':projectId',
   }
 
-  static examples = [
+  static openApi = {
-    {
+    '/modrinth/game-versions/{projectId}': {
-      title: 'Modrinth Game Versions',
+      get: {
-      namedParams: { projectId: 'AANobbMI' },
+        summary: 'Modrinth Game Versions',
-      staticPreview: this.render({ versions: ['1.19.2', '1.19.1', '1.19'] }),
+        description,
-      documentation,
+        parameters: pathParams({
+          name: 'projectId',
+          example: 'AANobbMI',
+        }),
+      },
     },
-  ]
+  }
 
   static defaultBadgeData = { label: 'game versions' }
 

services/modrinth/modrinth-version.service.js

@@ -1,5 +1,6 @@
+import { pathParams } from '../index.js'
 import { renderVersionBadge } from '../version.js'
-import { BaseModrinthService, documentation } from './modrinth-base.js'
+import { BaseModrinthService, description } from './modrinth-base.js'
 
 export default class ModrinthVersion extends BaseModrinthService {
   static category = 'version'
@@ -9,14 +10,18 @@ export default class ModrinthVersion extends BaseModrinthService {
     pattern: ':projectId',
   }
 
-  static examples = [
+  static openApi = {
-    {
+    '/modrinth/v/{projectId}': {
-      title: 'Modrinth Version',
+      get: {
-      namedParams: { projectId: 'AANobbMI' },
+        summary: 'Modrinth Version',
-      staticPreview: renderVersionBadge({ version: '0.4.4' }),
+        description,
-      documentation,
+        parameters: pathParams({
+          name: 'projectId',
+          example: 'AANobbMI',
+        }),
+      },
     },
-  ]
+  }
 
   static defaultBadgeData = { label: 'version' }
 

services/ore/ore-base.js

@@ -32,12 +32,11 @@ const resourceSchema = Joi.object({
   }).required(),
 }).required()
 
-const documentation = `
+const description = `
+<p><a href="https://ore.spongepowered.org/">Ore</a> is a Minecraft package repository.</p>
 <p>Your Plugin ID is the name of your plugin in lowercase, without any spaces or dashes.</p>
 <p>Example: <code>https://ore.spongepowered.org/Erigitic/Total-Economy</code> - Here the Plugin ID is <code>totaleconomy</code>.</p>`
 
-const keywords = ['sponge', 'spongemc', 'spongepowered']
-
 class BaseOreService extends BaseJsonService {
   async _refreshSessionToken() {
     const requestOptions = {
@@ -83,4 +82,4 @@ class BaseOreService extends BaseJsonService {
 
 BaseOreService.sessionToken = null
 
-export { keywords, documentation, BaseOreService }
+export { description, BaseOreService }

services/ore/ore-category.service.js

@@ -1,4 +1,5 @@
-import { BaseOreService, documentation, keywords } from './ore-base.js'
+import { pathParams } from '../index.js'
+import { BaseOreService, description } from './ore-base.js'
 
 export default class OreCategory extends BaseOreService {
   static category = 'other'
@@ -8,17 +9,18 @@ export default class OreCategory extends BaseOreService {
     pattern: ':pluginId',
   }
 
-  static examples = [
+  static openApi = {
-    {
+    '/ore/category/{pluginId}': {
-      title: 'Ore Category',
+      get: {
-      namedParams: {
+        summary: 'Ore Category',
-        pluginId: 'nucleus',
+        description,
+        parameters: pathParams({
+          name: 'pluginId',
+          example: 'nucleus',
+        }),
       },
-      staticPreview: this.render({ category: 'misc' }),
-      documentation,
-      keywords,
     },
-  ]
+  }
 
   static defaultBadgeData = {
     label: 'category',

services/ore/ore-downloads.service.js

@@ -1,5 +1,6 @@
+import { pathParams } from '../index.js'
 import { renderDownloadsBadge } from '../downloads.js'
-import { BaseOreService, documentation, keywords } from './ore-base.js'
+import { BaseOreService, description } from './ore-base.js'
 
 export default class OreDownloads extends BaseOreService {
   static category = 'downloads'
@@ -9,15 +10,18 @@ export default class OreDownloads extends BaseOreService {
     pattern: ':pluginId',
   }
 
-  static examples = [
+  static openApi = {
-    {
+    '/ore/dt/{pluginId}': {
-      title: 'Ore Downloads',
+      get: {
-      namedParams: { pluginId: 'nucleus' },
+        summary: 'Ore Downloads',
-      staticPreview: renderDownloadsBadge({ downloads: 560891 }),
+        description,
-      documentation,
+        parameters: pathParams({
-      keywords,
+          name: 'pluginId',
+          example: 'nucleus',
+        }),
+      },
     },
-  ]
+  }
 
   static defaultBadgeData = { label: 'downloads' }
 

services/ore/ore-license.service.js

@@ -1,5 +1,6 @@
+import { pathParams } from '../index.js'
 import { renderLicenseBadge } from '../licenses.js'
-import { BaseOreService, documentation, keywords } from './ore-base.js'
+import { BaseOreService, description } from './ore-base.js'
 
 export default class OreLicense extends BaseOreService {
   static category = 'license'
@@ -9,17 +10,18 @@ export default class OreLicense extends BaseOreService {
     pattern: ':pluginId',
   }
 
-  static examples = [
+  static openApi = {
-    {
+    '/ore/l/{pluginId}': {
-      title: 'Ore License',
+      get: {
-      namedParams: {
+        summary: 'Ore License',
-        pluginId: 'nucleus',
+        description,
+        parameters: pathParams({
+          name: 'pluginId',
+          example: 'nucleus',
+        }),
       },
-      staticPreview: this.render({ license: 'MIT' }),
-      documentation,
-      keywords,
     },
-  ]
+  }
 
   static defaultBadgeData = {
     label: 'license',

services/ore/ore-sponge-versions.service.js

@@ -1,4 +1,5 @@
-import { BaseOreService, documentation, keywords } from './ore-base.js'
+import { pathParams } from '../index.js'
+import { BaseOreService, description } from './ore-base.js'
 
 export default class OreSpongeVersions extends BaseOreService {
   static category = 'platform-support'
@@ -8,17 +9,18 @@ export default class OreSpongeVersions extends BaseOreService {
     pattern: ':pluginId',
   }
 
-  static examples = [
+  static openApi = {
-    {
+    '/ore/sponge-versions/{pluginId}': {
-      title: 'Compatible versions (plugins on Ore)',
+      get: {
-      namedParams: {
+        summary: 'Compatible versions (plugins on Ore)',
-        pluginId: 'nucleus',
+        description,
+        parameters: pathParams({
+          name: 'pluginId',
+          example: 'nucleus',
+        }),
       },
-      staticPreview: this.render({ versions: ['7.3', '6.0'] }),
-      documentation,
-      keywords,
     },
-  ]
+  }
 
   static defaultBadgeData = {
     label: 'sponge',

services/ore/ore-stars.service.js

@@ -1,5 +1,6 @@
+import { pathParams } from '../index.js'
 import { metric } from '../text-formatters.js'
-import { BaseOreService, documentation, keywords } from './ore-base.js'
+import { BaseOreService, description } from './ore-base.js'
 
 export default class OreStars extends BaseOreService {
   static category = 'rating'
@@ -9,17 +10,18 @@ export default class OreStars extends BaseOreService {
     pattern: ':pluginId',
   }
 
-  static examples = [
+  static openApi = {
-    {
+    '/ore/stars/{pluginId}': {
-      title: 'Ore Stars',
+      get: {
-      namedParams: {
+        summary: 'Ore Stars',
-        pluginId: 'nucleus',
+        description,
+        parameters: pathParams({
+          name: 'pluginId',
+          example: 'nucleus',
+        }),
       },
-      staticPreview: this.render({ stars: 1000 }),
-      documentation,
-      keywords,
     },
-  ]
+  }
 
   static defaultBadgeData = {
     label: 'stars',

services/ore/ore-version.service.js

@@ -1,5 +1,6 @@
+import { pathParams } from '../index.js'
 import { renderVersionBadge } from '../version.js'
-import { BaseOreService, documentation, keywords } from './ore-base.js'
+import { BaseOreService, description } from './ore-base.js'
 
 export default class OreVersion extends BaseOreService {
   static category = 'version'
@@ -9,17 +10,18 @@ export default class OreVersion extends BaseOreService {
     pattern: ':pluginId',
   }
 
-  static examples = [
+  static openApi = {
-    {
+    '/ore/v/{pluginId}': {
-      title: 'Ore Version',
+      get: {
-      namedParams: {
+        summary: 'Ore Version',
-        pluginId: 'nucleus',
+        description,
+        parameters: pathParams({
+          name: 'pluginId',
+          example: 'nucleus',
+        }),
       },
-      staticPreview: renderVersionBadge({ version: '2.2.3' }),
-      documentation,
-      keywords,
     },
-  ]
+  }
 
   static defaultBadgeData = {
     label: 'version',