migrate examples to openApi part 14; affects [azuredevops discord net…

…lify opencollective pub ros visualstudio] (#9560) * migrate some services from examples to openApi * migrate pub version * improve pub descriptions
badges · Dec 4, 2023 · 3eb4959 · 3eb4959
1 parent 0bda253
commit 3eb4959
Show file tree

Hide file tree

Showing 17 changed files with 278 additions and 192 deletions.
diff --git 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' }
 

diff --git 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
 

diff --git 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',

diff --git 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',

diff --git 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 }
diff --git 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' }
 

diff --git 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' }
 

diff --git 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' }
 

diff --git 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',

diff --git 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' }