migrate some services from examples to openApi (#9857)

services/poeditor/poeditor.service.js

@@ -1,16 +1,19 @@
 import Joi from 'joi'
 import { nonNegativeInteger } from '../validators.js'
 import { coveragePercentage } from '../color-formatters.js'
-import { BaseJsonService, InvalidResponse } from '../index.js'
+import {
+  BaseJsonService,
+  InvalidResponse,
+  pathParam,
+  queryParam,
+} from '../index.js'
 
-const documentation = `
-You must specify the read-only API token from the POEditor account to which the project belongs.
+const description = `
+POEditor is an web-based tool for translation and internationalization
 
-As per [the POEditor API documentation](https://poeditor.com/docs/api)
-
-> All requests to the API must contain the parameter api_token.
-> You can get a read-only key from your POEditor account.
-> You'll find it in [My Account > API Access](https://poeditor.com/account/api).
+All requests to must contain the parameter \`token\`.
+You can get a read-only token from your POEditor account in [My Account > API Access](https://poeditor.com/account/api).
+This token will be exposed as part of the badge URL so be sure to generate a read-only token.
 `
 
 const schema = Joi.object({
@@ -42,20 +45,25 @@ export default class POEditor extends BaseJsonService {
     queryParamSchema,
   }
 
-  static examples = [
-    {
-      title: 'POEditor',
-      namedParams: { projectId: '323337', languageCode: 'fr' },
-      queryParams: { token: 'abc123def456' },
-      staticPreview: this.render({
-        code: 200,
-        message: 'OK',
-        language: { percentage: 93, code: 'fr', name: 'French' },
-      }),
-      keywords: ['l10n'],
-      documentation,
+  static openApi = {
+    '/poeditor/progress/{projectId}/{languageCode}': {
+      get: {
+        summary: 'POEditor',
+        description,
+        parameters: [
+          pathParam({ name: 'projectId', example: '323337' }),
+          pathParam({ name: 'languageCode', example: 'fr' }),
+          queryParam({
+            name: 'token',
+            example: 'abc123def456',
+            description:
+              'A read-only token from your POEditor account from [My Account > API Access](https://poeditor.com/account/api)',
+            required: true,
+          }),
+        ],
+      },
     },
-  ]
+  }
 
   static render({ code, message, language }) {
     if (code !== 200) {

services/pypi/pypi-downloads.service.js

@@ -1,10 +1,8 @@
 import Joi from 'joi'
 import { nonNegativeInteger } from '../validators.js'
-import { BaseJsonService } from '../index.js'
+import { BaseJsonService, pathParams } from '../index.js'
 import { renderDownloadsBadge } from '../downloads.js'
 
-const keywords = ['python']
-
 const schema = Joi.object({
   data: Joi.object({
     last_day: nonNegativeInteger,
@@ -38,20 +36,24 @@ export default class PypiDownloads extends BaseJsonService {
     pattern: ':period(dd|dw|dm)/:packageName',
   }
 
-  static examples = [
-    {
-      title: 'PyPI - Downloads',
-      namedParams: {
-        period: 'dd',
-        packageName: 'Django',
+  static openApi = {
+    '/pypi/{period}/{packageName}': {
+      get: {
+        summary: 'PyPI - Downloads',
+        description:
+          'Python package downloads from [pypistats](https://pypistats.org/)',
+        parameters: pathParams(
+          {
+            name: 'period',
+            example: 'dd',
+            schema: { type: 'string', enum: this.getEnum('period') },
+            description: 'Daily, Weekly, or Monthly downloads',
+          },
+          { name: 'packageName', example: 'Django' },
+        ),
       },
-      staticPreview: renderDownloadsBadge({
-        interval: 'day',
-        downloads: 14000,
-      }),
-      keywords,
     },
-  ]
+  }
 
   static _cacheLength = 28800
 

services/pypi/pypi-framework-versions.service.js

@@ -1,4 +1,4 @@
-import { InvalidResponse } from '../index.js'
+import { InvalidResponse, pathParams } from '../index.js'
 import PypiBase from './pypi-base.js'
 import { sortPypiVersions, parseClassifiers } from './pypi-helpers.js'
 
@@ -37,7 +37,7 @@ const frameworkNameMap = {
   },
 }
 
-const documentation = `
+const description = `
 <p>
   This service currently support the following Frameworks: <br/>
   ${Object.values(frameworkNameMap).map(obj => ` <strong>${obj.name}</strong>`)}
@@ -53,21 +53,22 @@ export default class PypiFrameworkVersion extends PypiBase {
     )})/:packageName+`,
   }
 
-  static examples = [
-    {
-      title: 'PyPI - Versions from Framework Classifiers',
-      namedParams: {
-        frameworkName: 'Plone',
-        packageName: 'plone.volto',
+  static openApi = {
+    '/pypi/frameworkversions/{frameworkName}/{packageName}': {
+      get: {
+        summary: 'PyPI - Versions from Framework Classifiers',
+        description,
+        parameters: pathParams(
+          {
+            name: 'frameworkName',
+            example: 'plone',
+            schema: { type: 'string', enum: Object.keys(frameworkNameMap) },
+          },
+          { name: 'packageName', example: 'plone.volto' },
+        ),
       },
-      staticPreview: this.render({
-        name: 'Plone',
-        versions: ['5.2', '6.0'],
-      }),
-      keywords: ['python'],
-      documentation,
     },
-  ]
+  }
 
   static defaultBadgeData = { label: 'versions' }
 

services/symfony/symfony-insight-base.js

@@ -30,7 +30,8 @@ const schema = Joi.object({
   }).required(),
 }).required()
 
-const keywords = ['sensiolabs', 'sensio']
+const description =
+  'SymfonyInsight (formerly SensioLabs) is a code analysis service'
 
 const gradeColors = {
   none: 'red',
@@ -124,4 +125,4 @@ class SymfonyInsightBase extends BaseXmlService {
   }
 }
 
-export { SymfonyInsightBase, keywords, gradeColors }
+export { SymfonyInsightBase, description, gradeColors }

services/symfony/symfony-insight-grade.service.js

@@ -1,6 +1,7 @@
+import { pathParams } from '../index.js'
 import {
   SymfonyInsightBase,
-  keywords,
+  description,
   gradeColors,
 } from './symfony-insight-base.js'
 
@@ -10,19 +11,18 @@ export default class SymfonyInsightGrade extends SymfonyInsightBase {
     pattern: ':projectUuid',
   }
 
-  static examples = [
-    {
-      title: 'SymfonyInsight Grade',
-      namedParams: {
-        projectUuid: '825be328-29f8-44f7-a750-f82818ae9111',
+  static openApi = {
+    '/symfony/i/grade/{projectUuid}': {
+      get: {
+        summary: 'SymfonyInsight Grade',
+        description,
+        parameters: pathParams({
+          name: 'projectUuid',
+          example: '825be328-29f8-44f7-a750-f82818ae9111',
+        }),
       },
-      staticPreview: this.render({
-        grade: 'bronze',
-        status: 'finished',
-      }),
-      keywords,
     },
-  ]
+  }
 
   static render({ status, grade = 'none' }) {
     const label = 'grade'

services/symfony/symfony-insight-stars.service.js

@@ -1,7 +1,8 @@
+import { pathParams } from '../index.js'
 import { starRating } from '../text-formatters.js'
 import {
   SymfonyInsightBase,
-  keywords,
+  description,
   gradeColors,
 } from './symfony-insight-base.js'
 
@@ -19,19 +20,18 @@ export default class SymfonyInsightStars extends SymfonyInsightBase {
     pattern: ':projectUuid',
   }
 
-  static examples = [
-    {
-      title: 'SymfonyInsight Stars',
-      namedParams: {
-        projectUuid: '825be328-29f8-44f7-a750-f82818ae9111',
+  static openApi = {
+    '/symfony/i/stars/{projectUuid}': {
+      get: {
+        summary: 'SymfonyInsight Stars',
+        description,
+        parameters: pathParams({
+          name: 'projectUuid',
+          example: '825be328-29f8-44f7-a750-f82818ae9111',
+        }),
       },
-      staticPreview: this.render({
-        grade: 'silver',
-        status: 'finished',
-      }),
-      keywords,
     },
-  ]
+  }
 
   static render({ status, grade }) {
     const label = 'stars'

services/symfony/symfony-insight-violations.service.js

@@ -1,4 +1,5 @@
-import { SymfonyInsightBase, keywords } from './symfony-insight-base.js'
+import { pathParams } from '../index.js'
+import { SymfonyInsightBase, description } from './symfony-insight-base.js'
 
 export default class SymfonyInsightViolations extends SymfonyInsightBase {
   static route = {
@@ -6,19 +7,18 @@ export default class SymfonyInsightViolations extends SymfonyInsightBase {
     pattern: ':projectUuid',
   }
 
-  static examples = [
-    {
-      title: 'SymfonyInsight Violations',
-      namedParams: {
-        projectUuid: '825be328-29f8-44f7-a750-f82818ae9111',
+  static openApi = {
+    '/symfony/i/violations/{projectUuid}': {
+      get: {
+        summary: 'SymfonyInsight Violations',
+        description,
+        parameters: pathParams({
+          name: 'projectUuid',
+          example: '825be328-29f8-44f7-a750-f82818ae9111',
+        }),
       },
-      staticPreview: this.render({
-        numViolations: 0,
-        status: 'finished',
-      }),
-      keywords,
     },
-  ]
+  }
 
   static render({
     status,

services/teamcity/teamcity-build.service.js

@@ -1,5 +1,6 @@
 import Joi from 'joi'
 import { optionalUrl } from '../validators.js'
+import { pathParam, queryParam } from '../index.js'
 import TeamCityBase from './teamcity-base.js'
 
 const buildStatusSchema = Joi.object({
@@ -20,37 +21,35 @@ export default class TeamCityBuild extends TeamCityBase {
     queryParamSchema,
   }
 
-  static examples = [
-    {
-      title: 'TeamCity Simple Build Status',
-      namedParams: {
-        verbosity: 's',
-        buildId: 'IntelliJIdeaCe_JavaDecompilerEngineTests',
+  static openApi = {
+    '/teamcity/build/s/{buildId}': {
+      get: {
+        summary: 'TeamCity Simple Build Status',
+        parameters: [
+          pathParam({
+            name: 'buildId',
+            example: 'IntelliJIdeaCe_JavaDecompilerEngineTests',
+          }),
+          queryParam({
+            name: 'server',
+            example: 'https://teamcity.jetbrains.com',
+          }),
+        ],
       },
-      queryParams: {
-        server: 'https://teamcity.jetbrains.com',
-      },
-      staticPreview: this.render({
-        status: 'SUCCESS',
-      }),
     },
-    {
-      title: 'TeamCity Full Build Status',
-      namedParams: {
-        verbosity: 'e',
-        buildId: 'bt345',
+    '/teamcity/build/e/{buildId}': {
+      get: {
+        summary: 'TeamCity Full Build Status',
+        parameters: [
+          pathParam({ name: 'buildId', example: 'bt345' }),
+          queryParam({
+            name: 'server',
+            example: 'https://teamcity.jetbrains.com',
+          }),
+        ],
       },
-      queryParams: {
-        server: 'https://teamcity.jetbrains.com',
-      },
-      staticPreview: this.render({
-        status: 'FAILURE',
-        statusText: 'Tests failed: 4, passed: 1103, ignored: 2',
-        useVerbose: true,
-      }),
-      keywords: ['test', 'test results'],
     },
-  ]
+  }
 
   static defaultBadgeData = {
     label: 'build',

services/teamcity/teamcity-coverage.service.js

@@ -1,7 +1,7 @@
 import Joi from 'joi'
 import { coveragePercentage } from '../color-formatters.js'
 import { optionalUrl } from '../validators.js'
-import { InvalidResponse } from '../index.js'
+import { InvalidResponse, pathParam, queryParam } from '../index.js'
 import TeamCityBase from './teamcity-base.js'
 
 const buildStatisticsSchema = Joi.object({
@@ -28,20 +28,20 @@ export default class TeamCityCoverage extends TeamCityBase {
     queryParamSchema,
   }
 
-  static examples = [
-    {
-      title: 'TeamCity Coverage',
-      namedParams: {
-        buildId: 'ReactJSNet_PullRequests',
+  static openApi = {
+    '/teamcity/coverage/{buildId}': {
+      get: {
+        summary: 'TeamCity Coverage',
+        parameters: [
+          pathParam({ name: 'buildId', example: 'ReactJSNet_PullRequests' }),
+          queryParam({
+            name: 'server',
+            example: 'https://teamcity.jetbrains.com',
+          }),
+        ],
       },
-      queryParams: {
-        server: 'https://teamcity.jetbrains.com',
-      },
-      staticPreview: this.render({
-        coverage: 82,
-      }),
     },
-  ]
+  }
 
   static defaultBadgeData = {
     label: 'coverage',