migrate examples to openApi part 32; affects [azuredevops youtube] (b…

…adges#9861)

* migrate some services from examples to openApi

* Use testResultOpenApiQueryParams instead of redefining queryParams

services/azure-devops/azure-devops-build.service.js

@@ -1,14 +1,21 @@
 import Joi from 'joi'
 import { renderBuildStatusBadge } from '../build-status.js'
-import { BaseSvgScrapingService, NotFound } from '../index.js'
-import { keywords, fetch } from './azure-devops-helpers.js'
+import {
+  BaseSvgScrapingService,
+  NotFound,
+  queryParam,
+  pathParam,
+} from '../index.js'
+import { fetch } from './azure-devops-helpers.js'
 
 const queryParamSchema = Joi.object({
   stage: Joi.string(),
   job: Joi.string(),
 })
 
-const documentation = `
+const description = `
+[Azure Devops](https://dev.azure.com/) (formerly VSO, VSTS) is Microsoft Azure's CI/CD platform.
+
 A badge requires three pieces of information:
 \`ORGANIZATION\`, \`PROJECT_ID\` and \`DEFINITION_ID\`.
 
@@ -37,62 +44,68 @@ export default class AzureDevOpsBuild extends BaseSvgScrapingService {
     queryParamSchema,
   }
 
-  static examples = [
-    {
-      title: 'Azure DevOps builds',
-      pattern: ':organization/:projectId/:definitionId',
-      namedParams: {
-        organization: 'totodem',
-        projectId: '8cf3ec0e-d0c2-4fcd-8206-ad204f254a96',
-        definitionId: '2',
-      },
-      staticPreview: renderBuildStatusBadge({ status: 'succeeded' }),
-      keywords,
-      documentation,
-    },
-    {
-      title: 'Azure DevOps builds (branch)',
-      pattern: ':organization/:projectId/:definitionId/:branch',
-      namedParams: {
-        organization: 'totodem',
-        projectId: '8cf3ec0e-d0c2-4fcd-8206-ad204f254a96',
-        definitionId: '2',
-        branch: 'master',
-      },
-      staticPreview: renderBuildStatusBadge({ status: 'succeeded' }),
-      keywords,
-      documentation,
-    },
-    {
-      title: 'Azure DevOps builds (stage)',
-      namedParams: {
-        organization: 'totodem',
-        projectId: '8cf3ec0e-d0c2-4fcd-8206-ad204f254a96',
-        definitionId: '5',
-      },
-      queryParams: {
-        stage: 'Successful Stage',
+  static openApi = {
+    '/azure-devops/build/{organization}/{projectId}/{definitionId}': {
+      get: {
+        summary: 'Azure DevOps builds',
+        description,
+        parameters: [
+          pathParam({
+            name: 'organization',
+            example: 'totodem',
+          }),
+          pathParam({
+            name: 'projectId',
+            example: '8cf3ec0e-d0c2-4fcd-8206-ad204f254a96',
+          }),
+          pathParam({
+            name: 'definitionId',
+            example: '2',
+          }),
+          queryParam({
+            name: 'stage',
+            example: 'Successful Stage',
+          }),
+          queryParam({
+            name: 'job',
+            example: 'Successful Job',
+          }),
+        ],
       },
-      staticPreview: renderBuildStatusBadge({ status: 'succeeded' }),
-      keywords,
-      documentation,
     },
-    {
-      title: 'Azure DevOps builds (job)',
-      namedParams: {
-        organization: 'totodem',
-        projectId: '8cf3ec0e-d0c2-4fcd-8206-ad204f254a96',
-        definitionId: '5',
+    '/azure-devops/build/{organization}/{projectId}/{definitionId}/{branch}': {
+      get: {
+        summary: 'Azure DevOps builds (branch)',
+        description,
+        parameters: [
+          pathParam({
+            name: 'organization',
+            example: 'totodem',
+          }),
+          pathParam({
+            name: 'projectId',
+            example: '8cf3ec0e-d0c2-4fcd-8206-ad204f254a96',
+          }),
+          pathParam({
+            name: 'definitionId',
+            example: '2',
+          }),
+          pathParam({
+            name: 'branch',
+            example: 'master',
+          }),
+          queryParam({
+            name: 'stage',
+            example: 'Successful Stage',
+          }),
+          queryParam({
+            name: 'job',
+            example: 'Successful Job',
+          }),
+        ],
       },
-      queryParams: {
-        stage: 'Successful Stage',
-        job: 'Successful Job',
-      },
-      staticPreview: renderBuildStatusBadge({ status: 'succeeded' }),
-      keywords,
-      documentation,
     },
-  ]
+  }
 
   async handle(
     { organization, projectId, definitionId, branch },

services/azure-devops/azure-devops-helpers.js

@@ -1,8 +1,6 @@
 import Joi from 'joi'
 import { isBuildStatus } from '../build-status.js'
 
-const keywords = ['vso', 'vsts', 'azure-devops']
-
 const schema = Joi.object({
   message: Joi.alternatives()
     .try(
@@ -26,4 +24,4 @@ async function fetch(serviceInstance, { url, searchParams = {}, httpErrors }) {
   return { status }
 }
 
-export { keywords, fetch }
+export { fetch }

services/azure-devops/azure-devops-tests.service.js

@@ -1,28 +1,18 @@
 import Joi from 'joi'
+import { pathParam } from '../index.js'
 import {
+  testResultOpenApiQueryParams,
   testResultQueryParamSchema,
   renderTestResultBadge,
   documentation as commonDocumentation,
 } from '../test-results.js'
 import AzureDevOpsBase from './azure-devops-base.js'
 
-const commonAttrs = {
-  keywords: ['vso', 'vsts', 'azure-devops'],
-  namedParams: {
-    organization: 'azuredevops-powershell',
-    project: 'azuredevops-powershell',
-    definitionId: '1',
-    branch: 'master',
-  },
-  queryParams: {
-    passed_label: 'passed',
-    failed_label: 'failed',
-    skipped_label: 'skipped',
-    compact_message: null,
-  },
-  documentation: `
+const description = `
+[Azure Devops](https://dev.azure.com/) (formerly VSO, VSTS) is Microsoft Azure's CI/CD platform.
+
 To obtain your own badge, you need to get 3 pieces of information:
-\`ORGANIZATION\`, \`PROJECT_ID\`, \`DEFINITION_ID\`.
+\`ORGANIZATION\`, \`PROJECT\`, \`DEFINITION_ID\`.
 
 First, you need to select your build definition and look at the url:
 
@@ -37,8 +27,7 @@ Optionally, you can specify a named branch:
 \`https://img.shields.io/azure-devops/tests/ORGANIZATION/PROJECT/DEFINITION_ID/NAMED_BRANCH.svg\`.
 
 ${commonDocumentation}
-`,
-}
+`
 
 const buildTestResultSummarySchema = Joi.object({
   aggregatedResultsAnalysis: Joi.object({
@@ -65,48 +54,54 @@ export default class AzureDevOpsTests extends AzureDevOpsBase {
     queryParamSchema: testResultQueryParamSchema,
   }
 
-  static examples = [
-    {
-      title: 'Azure DevOps tests',
-      staticPreview: this.render({
-        passed: 20,
-        failed: 1,
-        skipped: 1,
-        total: 22,
-      }),
-      ...commonAttrs,
-    },
-    {
-      title: 'Azure DevOps tests (compact)',
-      staticPreview: this.render({
-        passed: 20,
-        failed: 1,
-        skipped: 1,
-        total: 22,
-        isCompact: true,
-      }),
-      ...commonAttrs,
+  static openApi = {
+    '/azure-devops/tests/{organization}/{project}/{definitionId}': {
+      get: {
+        summary: 'Azure DevOps tests',
+        description,
+        parameters: [
+          pathParam({
+            name: 'organization',
+            example: 'azuredevops-powershell',
+          }),
+          pathParam({
+            name: 'project',
+            example: 'azuredevops-powershell',
+          }),
+          pathParam({
+            name: 'definitionId',
+            example: '1',
+          }),
+          ...testResultOpenApiQueryParams,
+        ],
+      },
     },
-    {
-      title: 'Azure DevOps tests with custom labels',
-      queryParams: {
-        passed_label: 'good',
-        failed_label: 'bad',
-        skipped_label: 'n/a',
-        compact_message: null,
+    '/azure-devops/tests/{organization}/{project}/{definitionId}/{branch}': {
+      get: {
+        summary: 'Azure DevOps tests (branch)',
+        description,
+        parameters: [
+          pathParam({
+            name: 'organization',
+            example: 'azuredevops-powershell',
+          }),
+          pathParam({
+            name: 'project',
+            example: 'azuredevops-powershell',
+          }),
+          pathParam({
+            name: 'definitionId',
+            example: '1',
+          }),
+          pathParam({
+            name: 'branch',
+            example: 'master',
+          }),
+          ...testResultOpenApiQueryParams,
+        ],
       },
-      staticPreview: this.render({
-        passed: 20,
-        failed: 1,
-        skipped: 1,
-        total: 22,
-        passedLabel: 'good',
-        failedLabel: 'bad',
-        skippedLabel: 'n/a',
-      }),
-      ...commonAttrs,
     },
-  ]
+  }
 
   static defaultBadgeData = { label: 'tests' }
 

services/youtube/youtube-base.js

@@ -3,7 +3,7 @@ import { BaseJsonService, NotFound } from '../index.js'
 import { metric } from '../text-formatters.js'
 import { nonNegativeInteger } from '../validators.js'
 
-const documentation = `
+const description = `
 The YouTube badges provided by Shields.io leverage the YouTube API Services. By using this badge, you are:
 * agreeing to be bound by the YouTube Terms of Service, which can be found here: [https://www.youtube.com/t/terms](https://www.youtube.com/t/terms)
 * acknowledging and accepting the Google Privacy Policy, which can be found here: [https://policies.google.com/privacy](https://policies.google.com/privacy)
@@ -91,4 +91,4 @@ class YouTubeChannelBase extends YouTubeBase {
   static type = 'channel'
 }
 
-export { documentation, YouTubeVideoBase, YouTubeChannelBase }
+export { description, YouTubeVideoBase, YouTubeChannelBase }

services/youtube/youtube-channel-views.service.js

@@ -1,26 +1,23 @@
-import { documentation, YouTubeChannelBase } from './youtube-base.js'
+import { pathParams } from '../index.js'
+import { description, YouTubeChannelBase } from './youtube-base.js'
 
 export default class YouTubeChannelViews extends YouTubeChannelBase {
   static route = {
     base: 'youtube/channel/views',
     pattern: ':channelId',
   }
 
-  static get examples() {
-    const preview = this.render({
-      statistics: { viewCount: 30543 },
-      id: 'UC8butISFwT-Wl7EV0hUK0BQ',
-    })
-    // link[] is not allowed in examples
-    delete preview.link
-    return [
-      {
-        title: 'YouTube Channel Views',
-        namedParams: { channelId: 'UC8butISFwT-Wl7EV0hUK0BQ' },
-        staticPreview: preview,
-        documentation,
+  static openApi = {
+    '/youtube/channel/views/{channelId}': {
+      get: {
+        summary: 'YouTube Channel Views',
+        description,
+        parameters: pathParams({
+          name: 'channelId',
+          example: 'UC8butISFwT-Wl7EV0hUK0BQ',
+        }),
       },
-    ]
+    },
   }
 
   static render({ statistics, id }) {

services/youtube/youtube-comments.service.js

@@ -1,26 +1,23 @@
-import { documentation, YouTubeVideoBase } from './youtube-base.js'
+import { pathParams } from '../index.js'
+import { description, YouTubeVideoBase } from './youtube-base.js'
 
 export default class YouTubeComments extends YouTubeVideoBase {
   static route = {
     base: 'youtube/comments',
     pattern: ':videoId',
   }
 
-  static get examples() {
-    const preview = this.render({
-      statistics: { commentCount: 209 },
-      id: 'wGJHwc5ksMA',
-    })
-    // link[] is not allowed in examples
-    delete preview.link
-    return [
-      {
-        title: 'YouTube Video Comments',
-        namedParams: { videoId: 'wGJHwc5ksMA' },
-        staticPreview: preview,
-        documentation,
+  static openApi = {
+    '/youtube/comments/{videoId}': {
+      get: {
+        summary: 'YouTube Video Comments',
+        description,
+        parameters: pathParams({
+          name: 'videoId',
+          example: 'wGJHwc5ksMA',
+        }),
       },
-    ]
+    },
   }
 
   static render({ statistics, id }) {