migrate examples to openApi part 14; affects [azuredevops discord netlify opencollective pub ros visualstudio] (#9560)

* migrate some services from examples to openApi * migrate pub version * improve pub descriptions
2023-12-04 13:09:37 +00:00
parent 0bda253fe4
commit 3eb4959163
17 changed files with 278 additions and 192 deletions
--- a/services/azure-devops/azure-devops-release.service.js
+++ b/services/azure-devops/azure-devops-release.service.js
@@ -1,8 +1,8 @@
 import { renderBuildStatusBadge } from '../build-status.js'
-import { BaseSvgScrapingService } from '../index.js'
-import { keywords, fetch } from './azure-devops-helpers.js'
+import { BaseSvgScrapingService, pathParams } from '../index.js'
+import { fetch } from './azure-devops-helpers.js'

-const documentation = `
+const description = `
 To obtain your own badge, you need to get 4 pieces of information:
 \`ORGANIZATION\`, \`PROJECT_ID\`, \`DEFINITION_ID\` and \`ENVIRONMENT_ID\`.

@@ -25,20 +25,33 @@ export default class AzureDevOpsRelease extends BaseSvgScrapingService {
    pattern: ':organization/:projectId/:definitionId/:environmentId',
  }

-  static examples = [
-    {
-      title: 'Azure DevOps releases',
-      namedParams: {
-        organization: 'totodem',
-        projectId: '8cf3ec0e-d0c2-4fcd-8206-ad204f254a96',
-        definitionId: '1',
-        environmentId: '1',
+  static openApi = {
+    '/azure-devops/release/{organization}/{projectId}/{definitionId}/{environmentId}':
+      {
+        get: {
+          summary: 'Azure DevOps releases',
+          description,
+          parameters: pathParams(
+            {
+              name: 'organization',
+              example: 'totodem',
+            },
+            {
+              name: 'projectId',
+              example: '8cf3ec0e-d0c2-4fcd-8206-ad204f254a96',
+            },
+            {
+              name: 'definitionId',
+              example: '1',
+            },
+            {
+              name: 'environmentId',
+              example: '1',
+            },
+          ),
+        },
      },
-      staticPreview: renderBuildStatusBadge({ status: 'succeeded' }),
-      keywords,
-      documentation,
-    },
-  ]
+  }

  static defaultBadgeData = { label: 'deployment' }

--- a/services/discord/discord.service.js
+++ b/services/discord/discord.service.js
@@ -1,12 +1,12 @@
 import Joi from 'joi'
 import { nonNegativeInteger } from '../validators.js'
-import { BaseJsonService } from '../index.js'
+import { BaseJsonService, pathParams } from '../index.js'

 const schema = Joi.object({
  presence_count: nonNegativeInteger,
 }).required()

-const documentation = `
+const description = `
 <p>
  The Discord badge requires the <code>SERVER ID</code> in order access the Discord JSON API.
 </p>
@@ -36,14 +36,18 @@ export default class Discord extends BaseJsonService {
    isRequired: false,
  }

-  static examples = [
-    {
-      title: 'Discord',
-      namedParams: { serverId: '102860784329052160' },
-      staticPreview: this.render({ members: 23 }),
-      documentation,
+  static openApi = {
+    '/discord/{serverId}': {
+      get: {
+        summary: 'Discord',
+        description,
+        parameters: pathParams({
+          name: 'serverId',
+          example: '102860784329052160',
+        }),
+      },
    },
-  ]
+  }

  static _cacheLength = 30

--- a/services/netlify/netlify.service.js
+++ b/services/netlify/netlify.service.js
@@ -1,5 +1,5 @@
 import { renderBuildStatusBadge } from '../build-status.js'
-import { BaseSvgScrapingService } from '../index.js'
+import { BaseSvgScrapingService, pathParams } from '../index.js'

 const pendingStatus = 'building'
 const notBuiltStatus = 'not built'
@@ -22,17 +22,19 @@ export default class Netlify extends BaseSvgScrapingService {
    pattern: ':projectId',
  }

-  static examples = [
-    {
-      title: 'Netlify',
-      namedParams: {
-        projectId: 'e6d5a4e0-dee1-4261-833e-2f47f509c68f',
+  static openApi = {
+    '/netlify/{projectId}': {
+      get: {
+        summary: 'Netlify',
+        description:
+          'To locate your project id, visit your project settings, scroll to "Status badges" under "General", and copy the ID between "/api/v1/badges/" and "/deploy-status" in the code sample',
+        parameters: pathParams({
+          name: 'projectId',
+          example: 'e6d5a4e0-dee1-4261-833e-2f47f509c68f',
+        }),
      },
-      documentation:
-        'To locate your project id, visit your project settings, scroll to "Status badges" under "General", and copy the ID between "/api/v1/badges/" and "/deploy-status" in the code sample',
-      staticPreview: renderBuildStatusBadge({ status: 'passing' }),
    },
-  ]
+  }

  static defaultBadgeData = {
    label: 'netlify',
--- a/services/opencollective/opencollective-by-tier.service.js
+++ b/services/opencollective/opencollective-by-tier.service.js
@@ -1,9 +1,9 @@
 import Joi from 'joi'
 import { nonNegativeInteger } from '../validators.js'
-import { BaseJsonService } from '../index.js'
+import { BaseJsonService, pathParams } from '../index.js'
 import { metric } from '../text-formatters.js'

-const documentation = `<h3>How to get the tierId</h3>
+const description = `<h3>How to get the tierId</h3>
 <p>According to <a target="_blank" href="https://developer.opencollective.com/#/api/collectives?id=get-members-per-tier">open collectives documentation</a>, you can find the tierId by looking at the URL after clicking on a Tier Card on the collective page. (e.g. tierId for https://opencollective.com/shields/order/2988 is 2988)</p>`

 // https://developer.opencollective.com/#/api/collectives?id=get-info
@@ -88,15 +88,24 @@ class OpencollectiveBaseJson extends BaseJsonService {
 export default class OpencollectiveByTier extends OpencollectiveBaseJson {
  static route = this.buildRoute('tier', true)

-  static examples = [
-    {
-      title: 'Open Collective members by tier',
-      namedParams: { collective: 'shields', tierId: '2988' },
-      staticPreview: this.render(8, 'monthly backers'),
-      keywords: ['opencollective'],
-      documentation,
+  static openApi = {
+    '/opencollective/tier/{collective}/{tierId}': {
+      get: {
+        summary: 'Open Collective members by tier',
+        description,
+        parameters: pathParams(
+          {
+            name: 'collective',
+            example: 'shields',
+          },
+          {
+            name: 'tierId',
+            example: '2988',
+          },
+        ),
+      },
    },
-  ]
+  }

  static defaultBadgeData = {
    label: 'open collective',
--- a/services/pub/pub-common.js
+++ b/services/pub/pub-common.js
@@ -0,0 +1,4 @@
+const baseDescription =
+  '<p><a href="https://pub.dev/">Pub</a> is a package registry for Dart and Flutter.</p>'
+
+export { baseDescription }
--- a/services/pub/pub-likes.service.js
+++ b/services/pub/pub-likes.service.js
@@ -1,33 +1,33 @@
 import Joi from 'joi'
-import { BaseJsonService } from '../index.js'
+import { BaseJsonService, pathParams } from '../index.js'
 import { metric } from '../text-formatters.js'
 import { nonNegativeInteger } from '../validators.js'
+import { baseDescription } from './pub-common.js'

-const documentation =
-  '<p>A measure of how many developers have liked a package. This provides a raw measure of the overall sentiment of a package from peer developers.</p>'
-
-const keywords = ['dart', 'flutter']
+const description = `${baseDescription}
+  <p>This badge shows a measure of how many developers have liked a package. This provides a raw measure of the overall sentiment of a package from peer developers.</p>`

 const schema = Joi.object({
  likeCount: nonNegativeInteger,
 }).required()

-const title = 'Pub Likes'
-
 export default class PubLikes extends BaseJsonService {
  static category = 'rating'

  static route = { base: 'pub/likes', pattern: ':packageName' }

-  static examples = [
-    {
-      title,
-      keywords,
-      documentation,
-      namedParams: { packageName: 'analysis_options' },
-      staticPreview: this.render({ likeCount: 1000 }),
+  static openApi = {
+    '/pub/likes/{packageName}': {
+      get: {
+        summary: 'Pub Likes',
+        description,
+        parameters: pathParams({
+          name: 'packageName',
+          example: 'analysis_options',
+        }),
+      },
    },
-  ]
+  }

  static defaultBadgeData = { label: 'likes' }

--- a/services/pub/pub-points.service.js
+++ b/services/pub/pub-points.service.js
@@ -1,34 +1,34 @@
 import Joi from 'joi'
 import { floorCount } from '../color-formatters.js'
-import { BaseJsonService } from '../index.js'
+import { BaseJsonService, pathParams } from '../index.js'
 import { nonNegativeInteger } from '../validators.js'
+import { baseDescription } from './pub-common.js'

-const documentation =
-  '<p>A measure of quality. This includes several dimensions of quality such as code style, platform support, and maintainability.</p>'
-
-const keywords = ['dart', 'flutter']
+const description = `${baseDescription}
+  <p>This badge shows a measure of quality. This includes several dimensions of quality such as code style, platform support, and maintainability.</p>`

 const schema = Joi.object({
  grantedPoints: nonNegativeInteger,
  maxPoints: nonNegativeInteger,
 }).required()

-const title = 'Pub Points'
-
 export default class PubPoints extends BaseJsonService {
  static category = 'rating'

  static route = { base: 'pub/points', pattern: ':packageName' }

-  static examples = [
-    {
-      title,
-      keywords,
-      documentation,
-      namedParams: { packageName: 'analysis_options' },
-      staticPreview: this.render({ grantedPoints: 120, maxPoints: 140 }),
+  static openApi = {
+    '/pub/points/{packageName}': {
+      get: {
+        summary: 'Pub Points',
+        description,
+        parameters: pathParams({
+          name: 'packageName',
+          example: 'analysis_options',
+        }),
+      },
    },
-  ]
+  }

  static defaultBadgeData = { label: 'points' }

--- a/services/pub/pub-popularity.service.js
+++ b/services/pub/pub-popularity.service.js
@@ -1,32 +1,32 @@
 import Joi from 'joi'
 import { floorCount } from '../color-formatters.js'
-import { BaseJsonService } from '../index.js'
+import { BaseJsonService, pathParams } from '../index.js'
+import { baseDescription } from './pub-common.js'

-const documentation =
-  '<p>A measure of how many developers use a package, providing insight into what other developers are using.</p>'
-
-const keywords = ['dart', 'flutter']
+const description = `${baseDescription}
+  <p>This badge shows a measure of how many developers use a package, providing insight into what other developers are using.</p>`

 const schema = Joi.object({
  popularityScore: Joi.number().min(0).max(1).required(),
 }).required()

-const title = 'Pub Popularity'
-
 export default class PubPopularity extends BaseJsonService {
  static category = 'rating'

  static route = { base: 'pub/popularity', pattern: ':packageName' }

-  static examples = [
-    {
-      title,
-      keywords,
-      documentation,
-      namedParams: { packageName: 'analysis_options' },
-      staticPreview: this.render({ popularityScore: 0.9 }),
+  static openApi = {
+    '/pub/popularity/{packageName}': {
+      get: {
+        summary: 'Pub Popularity',
+        description,
+        parameters: pathParams({
+          name: 'packageName',
+          example: 'analysis_options',
+        }),
+      },
    },
-  ]
+  }

  static defaultBadgeData = { label: 'popularity' }

--- a/services/pub/pub-publisher.service.js
+++ b/services/pub/pub-publisher.service.js
@@ -1,5 +1,6 @@
 import Joi from 'joi'
 import { BaseJsonService, pathParams } from '../index.js'
+import { baseDescription } from './pub-common.js'

 const schema = Joi.object({
  publisherId: Joi.string().allow(null).required(),
@@ -17,6 +18,7 @@ export class PubPublisher extends BaseJsonService {
    '/pub/publisher/{packageName}': {
      get: {
        summary: 'Pub Publisher',
+        description: baseDescription,
        parameters: pathParams({
          name: 'packageName',
          example: 'path',
--- a/services/pub/pub.service.js
+++ b/services/pub/pub.service.js
@@ -1,6 +1,7 @@
 import Joi from 'joi'
 import { latest, renderVersionBadge } from '../version.js'
-import { BaseJsonService, redirector } from '../index.js'
+import { BaseJsonService, redirector, pathParam, queryParam } from '../index.js'
+import { baseDescription } from './pub-common.js'

 const schema = Joi.object({
  versions: Joi.array().items(Joi.string()).required(),
@@ -19,21 +20,25 @@ class PubVersion extends BaseJsonService {
    queryParamSchema,
  }

-  static examples = [
-    {
-      title: 'Pub Version',
-      namedParams: { packageName: 'box2d' },
-      staticPreview: renderVersionBadge({ version: 'v0.4.0' }),
-      keywords: ['dart', 'dartlang'],
+  static openApi = {
+    '/pub/v/{packageName}': {
+      get: {
+        summary: 'Pub Version',
+        description: baseDescription,
+        parameters: [
+          pathParam({
+            name: 'packageName',
+            example: 'box2d',
+          }),
+          queryParam({
+            name: 'include_prereleases',
+            schema: { type: 'boolean' },
+            example: null,
+          }),
+        ],
+      },
    },
-    {
-      title: 'Pub Version (including pre-releases)',
-      namedParams: { packageName: 'box2d' },
-      queryParams: { include_prereleases: null },
-      staticPreview: renderVersionBadge({ version: 'v0.4.0' }),
-      keywords: ['dart', 'dartlang'],
-    },
-  ]
+  }

  static defaultBadgeData = { label: 'pub' }

--- a/services/ros/ros-version.service.js
+++ b/services/ros/ros-version.service.js
@@ -3,7 +3,7 @@ import Joi from 'joi'
 import yaml from 'js-yaml'
 import { renderVersionBadge } from '../version.js'
 import { GithubAuthV4Service } from '../github/github-auth-service.js'
-import { NotFound, InvalidResponse } from '../index.js'
+import { NotFound, InvalidResponse, pathParams } from '../index.js'

 const tagsSchema = Joi.object({
  data: Joi.object({
@@ -40,7 +40,7 @@ const repoSchema = Joi.object({
  }).required(),
 })

-const documentation = `
+const description = `
 <p>
  To use this badge, specify the ROS <a href="http://docs.ros.org">distribution</a>
  (e.g. <code>noetic</code> or <code>humble</code>) and the package repository name
@@ -56,17 +56,24 @@ export default class RosVersion extends GithubAuthV4Service {

  static route = { base: 'ros/v', pattern: ':distro/:repoName' }

-  static examples = [
-    {
-      title: 'ROS Package Index',
-      namedParams: { distro: 'humble', repoName: 'vision_msgs' },
-      staticPreview: {
-        ...renderVersionBadge({ version: '4.0.0' }),
-        label: 'ros | humble',
+  static openApi = {
+    '/ros/v/{distro}/{repoName}': {
+      get: {
+        summary: 'ROS Package Index',
+        description,
+        parameters: pathParams(
+          {
+            name: 'distro',
+            example: 'humble',
+          },
+          {
+            name: 'repoName',
+            example: 'vision_msgs',
+          },
+        ),
      },
-      documentation,
    },
-  ]
+  }

  static defaultBadgeData = { label: 'ros' }

--- a/services/tokei/tokei.service.js
+++ b/services/tokei/tokei.service.js
@@ -1,13 +1,13 @@
 import Joi from 'joi'
 import { metric } from '../text-formatters.js'
 import { nonNegativeInteger } from '../validators.js'
-import { BaseJsonService } from '../index.js'
+import { BaseJsonService, pathParams } from '../index.js'

 const schema = Joi.object({
  lines: nonNegativeInteger,
 }).required()

-const documentation = `
+const description = `
 The \`provider\` is the domain name of git host.
 If no TLD is provided, \`.com\` will be added.
 For example, setting \`gitlab\` or \`bitbucket.org\` as the
@@ -26,19 +26,28 @@ export default class Tokei extends BaseJsonService {

  static route = { base: 'tokei/lines', pattern: ':provider/:user/:repo' }

-  static examples = [
-    {
-      title: 'Lines of code',
-      namedParams: {
-        provider: 'github',
-        user: 'badges',
-        repo: 'shields',
+  static openApi = {
+    '/tokei/lines/{provider}/{user}/{repo}': {
+      get: {
+        summary: 'Lines of code',
+        description,
+        parameters: pathParams(
+          {
+            name: 'provider',
+            example: 'github',
+          },
+          {
+            name: 'user',
+            example: 'badges',
+          },
+          {
+            name: 'repo',
+            example: 'shields',
+          },
+        ),
      },
-      staticPreview: this.render({ lines: 119500 }),
-      keywords: ['loc', 'tokei'],
-      documentation,
    },
-  ]
+  }

  static defaultBadgeData = {
    label: 'total lines',
--- a/services/visual-studio-app-center/visual-studio-app-center-base.js
+++ b/services/visual-studio-app-center/visual-studio-app-center-base.js
@@ -1,13 +1,6 @@
 import { BaseJsonService } from '../index.js'

-const keywords = [
-  'visual-studio',
-  'vsac',
-  'visual-studio-app-center',
-  'app-center',
-]
-
-const documentation =
+const description =
  "You will need to create a <b>read-only</b> API token <a target='_blank' href='https://appcenter.ms/settings/apitokens'>here</a>."

 class BaseVisualStudioAppCenterService extends BaseJsonService {
@@ -35,4 +28,4 @@ class BaseVisualStudioAppCenterService extends BaseJsonService {
  }
 }

-export { keywords, documentation, BaseVisualStudioAppCenterService }
+export { description, BaseVisualStudioAppCenterService }
--- a/services/visual-studio-app-center/visual-studio-app-center-builds.service.js
+++ b/services/visual-studio-app-center/visual-studio-app-center-builds.service.js
@@ -1,10 +1,9 @@
 import Joi from 'joi'
 import { isBuildStatus, renderBuildStatusBadge } from '../build-status.js'
-import { NotFound } from '../index.js'
+import { NotFound, pathParams } from '../index.js'
 import {
  BaseVisualStudioAppCenterService,
-  keywords,
-  documentation,
+  description,
 } from './visual-studio-app-center-base.js'

 const schema = Joi.array().items({
@@ -19,20 +18,32 @@ export default class VisualStudioAppCenterBuilds extends BaseVisualStudioAppCent
    pattern: ':owner/:app/:branch/:token',
  }

-  static examples = [
-    {
-      title: 'Visual Studio App Center Builds',
-      namedParams: {
-        owner: 'jct',
-        app: 'my-amazing-app',
-        branch: 'master',
-        token: 'ac70cv...',
+  static openApi = {
+    '/visual-studio-app-center/builds/{owner}/{app}/{branch}/{token}': {
+      get: {
+        summary: 'Visual Studio App Center Builds',
+        description,
+        parameters: pathParams(
+          {
+            name: 'owner',
+            example: 'jct',
+          },
+          {
+            name: 'app',
+            example: 'my-amazing-app',
+          },
+          {
+            name: 'branch',
+            example: 'master',
+          },
+          {
+            name: 'token',
+            example: 'ac70cv...',
+          },
+        ),
      },
-      staticPreview: renderBuildStatusBadge({ status: 'succeeded' }),
-      keywords,
-      documentation,
    },
-  ]
+  }

  static defaultBadgeData = {
    label: 'build',
--- a/services/visual-studio-app-center/visual-studio-app-center-releases-osversion.service.js
+++ b/services/visual-studio-app-center/visual-studio-app-center-releases-osversion.service.js
@@ -1,8 +1,8 @@
 import Joi from 'joi'
+import { pathParams } from '../index.js'
 import {
  BaseVisualStudioAppCenterService,
-  keywords,
-  documentation,
+  description,
 } from './visual-studio-app-center-base.js'

 const schema = Joi.object({
@@ -18,19 +18,28 @@ export default class VisualStudioAppCenterReleasesOSVersion extends BaseVisualSt
    pattern: ':owner/:app/:token',
  }

-  static examples = [
-    {
-      title: 'Visual Studio App Center (Minimum) OS Version',
-      namedParams: {
-        owner: 'jct',
-        app: 'my-amazing-app',
-        token: 'ac70cv...',
+  static openApi = {
+    '/visual-studio-app-center/releases/osver/{owner}/{app}/{token}': {
+      get: {
+        summary: 'Visual Studio App Center (Minimum) OS Version',
+        description,
+        parameters: pathParams(
+          {
+            name: 'owner',
+            example: 'jct',
+          },
+          {
+            name: 'app',
+            example: 'my-amazing-app',
+          },
+          {
+            name: 'token',
+            example: 'ac70cv...',
+          },
+        ),
      },
-      staticPreview: this.render({ minOS: '4.1', appOS: 'Android' }),
-      keywords,
-      documentation,
    },
-  ]
+  }

  static defaultBadgeData = {
    label: 'min version',
--- a/services/visual-studio-app-center/visual-studio-app-center-releases-size.service.js
+++ b/services/visual-studio-app-center/visual-studio-app-center-releases-size.service.js
@@ -1,10 +1,10 @@
 import Joi from 'joi'
 import prettyBytes from 'pretty-bytes'
+import { pathParams } from '../index.js'
 import { nonNegativeInteger } from '../validators.js'
 import {
  BaseVisualStudioAppCenterService,
-  keywords,
-  documentation,
+  description,
 } from './visual-studio-app-center-base.js'

 const schema = Joi.object({
@@ -19,19 +19,28 @@ export default class VisualStudioAppCenterReleasesSize extends BaseVisualStudioA
    pattern: ':owner/:app/:token',
  }

-  static examples = [
-    {
-      title: 'Visual Studio App Center Size',
-      namedParams: {
-        owner: 'jct',
-        app: 'my-amazing-app',
-        token: 'ac70cv...',
+  static openApi = {
+    '/visual-studio-app-center/releases/size/{owner}/{app}/{token}': {
+      get: {
+        summary: 'Visual Studio App Center Size',
+        description,
+        parameters: pathParams(
+          {
+            name: 'owner',
+            example: 'jct',
+          },
+          {
+            name: 'app',
+            example: 'my-amazing-app',
+          },
+          {
+            name: 'token',
+            example: 'ac70cv...',
+          },
+        ),
      },
-      staticPreview: this.render({ size: 8368844 }),
-      keywords,
-      documentation,
    },
-  ]
+  }

  static defaultBadgeData = {
    label: 'size',
--- a/services/visual-studio-app-center/visual-studio-app-center-releases-version.service.js
+++ b/services/visual-studio-app-center/visual-studio-app-center-releases-version.service.js
@@ -1,9 +1,9 @@
 import Joi from 'joi'
+import { pathParams } from '../index.js'
 import { renderVersionBadge } from '../version.js'
 import {
  BaseVisualStudioAppCenterService,
-  keywords,
-  documentation,
+  description,
 } from './visual-studio-app-center-base.js'

 const schema = Joi.object({
@@ -19,19 +19,28 @@ export default class VisualStudioAppCenterReleasesVersion extends BaseVisualStud
    pattern: ':owner/:app/:token',
  }

-  static examples = [
-    {
-      title: 'Visual Studio App Center Releases',
-      namedParams: {
-        owner: 'jct',
-        app: 'my-amazing-app',
-        token: 'ac70cv...',
+  static openApi = {
+    '/visual-studio-app-center/releases/version/{owner}/{app}/{token}': {
+      get: {
+        summary: 'Visual Studio App Center Releases',
+        description,
+        parameters: pathParams(
+          {
+            name: 'owner',
+            example: 'jct',
+          },
+          {
+            name: 'app',
+            example: 'my-amazing-app',
+          },
+          {
+            name: 'token',
+            example: 'ac70cv...',
+          },
+        ),
      },
-      staticPreview: renderVersionBadge({ version: '1.0 (4)' }),
-      keywords,
-      documentation,
    },
-  ]
+  }

  static defaultBadgeData = {
    label: 'release',