migrate examples to openApi part 33; affects [bower drone localizely …

…mozillaobservatory pythonversionfromtoml] (#9864)

* migrate some services from examples to openApi

* Fix Drone examples and tests

* Separate Mozilla Observatory publish documentation

services/bower/bower-version.service.js

@@ -1,18 +1,22 @@
 import { renderVersionBadge } from '../version.js'
-import { InvalidResponse } from '../index.js'
+import { InvalidResponse, pathParams } from '../index.js'
 import BaseBowerService from './bower-base.js'
 
 export default class BowerVersion extends BaseBowerService {
   static category = 'version'
   static route = { base: 'bower/v', pattern: ':packageName' }
 
-  static examples = [
-    {
-      title: 'Bower Version',
-      namedParams: { packageName: 'bootstrap' },
-      staticPreview: renderVersionBadge({ version: '4.2.1' }),
+  static openApi = {
+    '/bower/v/{packageName}': {
+      get: {
+        summary: 'Bower Version',
+        parameters: pathParams({
+          name: 'packageName',
+          example: 'bootstrap',
+        }),
+      },
     },
-  ]
+  }
 
   static defaultBadgeData = { label: 'bower' }
 

services/drone/drone-build.service.js

@@ -1,7 +1,7 @@
 import Joi from 'joi'
 import { isBuildStatus, renderBuildStatusBadge } from '../build-status.js'
 import { optionalUrl } from '../validators.js'
-import { BaseJsonService } from '../index.js'
+import { BaseJsonService, queryParam, pathParam } from '../index.js'
 
 const schema = Joi.object({
   status: Joi.alternatives()
@@ -22,48 +22,51 @@ export default class DroneBuild extends BaseJsonService {
   }
 
   static auth = { passKey: 'drone_token', serviceKey: 'drone' }
-  static examples = [
-    {
-      title: 'Drone (cloud)',
-      pattern: ':user/:repo',
-      namedParams: {
-        user: 'harness',
-        repo: 'drone',
-      },
-      staticPreview: renderBuildStatusBadge({ status: 'success' }),
-    },
-    {
-      title: 'Drone (cloud) with branch',
-      pattern: ':user/:repo/:branch',
-      namedParams: {
-        user: 'harness',
-        repo: 'drone',
-        branch: 'master',
-      },
-      staticPreview: renderBuildStatusBadge({ status: 'success' }),
-    },
-    {
-      title: 'Drone (self-hosted)',
-      pattern: ':user/:repo',
-      queryParams: { server: 'https://drone.shields.io' },
-      namedParams: {
-        user: 'badges',
-        repo: 'shields',
+
+  static openApi = {
+    '/drone/build/{user}/{repo}': {
+      get: {
+        summary: 'Drone',
+        parameters: [
+          pathParam({
+            name: 'user',
+            example: 'drone',
+          }),
+          pathParam({
+            name: 'repo',
+            example: 'autoscaler',
+          }),
+          queryParam({
+            name: 'server',
+            example: 'https://drone.shields.io',
+          }),
+        ],
       },
-      staticPreview: renderBuildStatusBadge({ status: 'success' }),
     },
-    {
-      title: 'Drone (self-hosted) with branch',
-      pattern: ':user/:repo/:branch',
-      queryParams: { server: 'https://drone.shields.io' },
-      namedParams: {
-        user: 'badges',
-        repo: 'shields',
-        branch: 'feat/awesome-thing',
+    '/drone/build/{user}/{repo}/{branch}': {
+      get: {
+        summary: 'Drone (branch)',
+        parameters: [
+          pathParam({
+            name: 'user',
+            example: 'drone',
+          }),
+          pathParam({
+            name: 'repo',
+            example: 'autoscaler',
+          }),
+          pathParam({
+            name: 'branch',
+            example: 'master',
+          }),
+          queryParam({
+            name: 'server',
+            example: 'https://drone.shields.io',
+          }),
+        ],
       },
-      staticPreview: renderBuildStatusBadge({ status: 'success' }),
     },
-  ]
+  }
 
   static defaultBadgeData = { label: 'build' }
 

services/drone/drone-build.tester.js

@@ -10,14 +10,14 @@ const isDroneBuildStatus = Joi.alternatives().try(
 )
 
 t.create('cloud-hosted build status on default branch')
-  .get('/harness/drone.json')
+  .get('/drone/autoscaler.json')
   .expectBadge({
     label: 'build',
     message: isDroneBuildStatus,
   })
 
 t.create('cloud-hosted build status on named branch')
-  .get('/harness/drone/master.json')
+  .get('/drone/autoscaler/master.json')
   .expectBadge({
     label: 'build',
     message: isDroneBuildStatus,

services/localizely/localizely.service.js

@@ -1,18 +1,16 @@
 import Joi from 'joi'
-import { BaseJsonService, InvalidResponse } from '../index.js'
+import {
+  BaseJsonService,
+  InvalidResponse,
+  queryParam,
+  pathParam,
+} from '../index.js'
 import { coveragePercentage } from '../color-formatters.js'
 
-const keywords = [
-  'l10n',
-  'i18n',
-  'localization',
-  'internationalization',
-  'translation',
-  'translations',
-]
-
-const documentation = `
+const description = `
   <p>
+    <a href="https://localizely.com/" target="_blank">Localizely</a> is a management system for translation, localization, and internationalization of your projects.
+    <br/>
     The <b>read-only</b> API token from the Localizely account is required to fetch necessary data.
     <br/>
     <br/>
@@ -58,40 +56,58 @@ export default class Localizely extends BaseJsonService {
     queryParamSchema,
   }
 
-  static examples = [
-    {
-      title: 'Localizely overall progress',
-      keywords,
-      documentation,
-      namedParams: {
-        projectId: '5cc34208-0418-40b1-8353-acc70c95f802',
-        branch: 'main',
-      },
-      queryParams: {
-        token:
-          '0f4d5e31a44f48dcbab966c52cfb0a67c5f1982186c14b85ab389a031dbc225a',
+  static openApi = {
+    '/localizely/progress/{projectId}': {
+      get: {
+        summary: 'Localizely progress',
+        description,
+        parameters: [
+          pathParam({
+            name: 'projectId',
+            example: '5cc34208-0418-40b1-8353-acc70c95f802',
+          }),
+          queryParam({
+            name: 'token',
+            example:
+              '0f4d5e31a44f48dcbab966c52cfb0a67c5f1982186c14b85ab389a031dbc225a',
+            required: true,
+          }),
+          queryParam({
+            name: 'languageCode',
+            example: 'en-US',
+            required: false,
+          }),
+        ],
       },
-      staticPreview: this.render({ reviewedProgress: 93 }),
     },
-    {
-      title: 'Localizely language progress',
-      keywords,
-      documentation,
-      namedParams: {
-        projectId: '5cc34208-0418-40b1-8353-acc70c95f802',
-        branch: 'main',
+    '/localizely/progress/{projectId}/{branch}': {
+      get: {
+        summary: 'Localizely progress (branch)',
+        description,
+        parameters: [
+          pathParam({
+            name: 'projectId',
+            example: '5cc34208-0418-40b1-8353-acc70c95f802',
+          }),
+          pathParam({
+            name: 'branch',
+            example: 'main',
+          }),
+          queryParam({
+            name: 'token',
+            example:
+              '0f4d5e31a44f48dcbab966c52cfb0a67c5f1982186c14b85ab389a031dbc225a',
+            required: true,
+          }),
+          queryParam({
+            name: 'languageCode',
+            example: 'en-US',
+            required: false,
+          }),
+        ],
       },
-      queryParams: {
-        token:
-          '0f4d5e31a44f48dcbab966c52cfb0a67c5f1982186c14b85ab389a031dbc225a',
-        languageCode: 'en-US',
-      },
-      staticPreview: this.render({
-        langName: 'English (US)',
-        reviewedProgress: 97,
-      }),
     },
-  ]
+  }
 
   static defaultBadgeData = { label: 'localized' }
 

services/mozilla-observatory/mozilla-observatory.service.js

@@ -1,5 +1,5 @@
 import Joi from 'joi'
-import { BaseJsonService } from '../index.js'
+import { BaseJsonService, queryParam, pathParam } from '../index.js'
 
 const schema = Joi.object({
   state: Joi.string()
@@ -25,11 +25,13 @@ const queryParamSchema = Joi.object({
   publish: Joi.equal(''),
 }).required()
 
-const documentation = `
+const description = `
 The [Mozilla HTTP Observatory](https://observatory.mozilla.org)
-is a set of tools to analyze your website
+is a set of security tools to analyze your website
 and inform you if you are utilizing the many available methods to secure it.
+`
 
+const publishDescription = `
 By default the scan result is hidden from the public result list.
 You can activate the publication of the scan result
 by setting the \`publish\` parameter.
@@ -50,21 +52,31 @@ export default class MozillaObservatory extends BaseJsonService {
     queryParamSchema,
   }
 
-  static examples = [
-    {
-      title: 'Mozilla HTTP Observatory Grade',
-      namedParams: { format: 'grade', host: 'github.com' },
-      staticPreview: this.render({
-        format: 'grade',
-        state: 'FINISHED',
-        grade: 'A+',
-        score: 115,
-      }),
-      queryParams: { publish: null },
-      keywords: ['scanner', 'security'],
-      documentation,
+  static openApi = {
+    '/mozilla-observatory/{format}/{host}': {
+      get: {
+        summary: 'Mozilla HTTP Observatory Grade',
+        description,
+        parameters: [
+          pathParam({
+            name: 'format',
+            example: 'grade',
+            schema: { type: 'string', enum: this.getEnum('format') },
+          }),
+          pathParam({
+            name: 'host',
+            example: 'github.com',
+          }),
+          queryParam({
+            name: 'publish',
+            schema: { type: 'boolean' },
+            example: null,
+            description: publishDescription,
+          }),
+        ],
+      },
     },
-  ]
+  }
 
   static defaultBadgeData = {
     label: 'observatory',

services/python/python-version-from-toml.service.js

@@ -1,5 +1,6 @@
 import Joi from 'joi'
 import BaseTomlService from '../../core/base-service/base-toml.js'
+import { queryParams } from '../index.js'
 import { optionalUrl } from '../validators.js'
 
 const queryParamSchema = Joi.object({
@@ -12,7 +13,7 @@ const schema = Joi.object({
   }).required(),
 }).required()
 
-const documentation = `Shows the required python version for a package based on the values in the requires-python field in PEP 621 compliant pyproject.toml \n
+const description = `Shows the required python version for a package based on the values in the requires-python field in PEP 621 compliant pyproject.toml \n
 a URL of the toml is required, please note that when linking to files in github or similar sites, provide URL to raw file, for example:
 
 Use https://raw.githubusercontent.com/numpy/numpy/main/pyproject.toml \n
@@ -28,18 +29,20 @@ class PythonVersionFromToml extends BaseTomlService {
     queryParamSchema,
   }
 
-  static examples = [
-    {
-      title: 'Python Version from PEP 621 TOML',
-      namedParams: {},
-      queryParams: {
-        tomlFilePath:
-          'https://raw.githubusercontent.com/numpy/numpy/main/pyproject.toml',
+  static openApi = {
+    '/python/required-version-toml': {
+      get: {
+        summary: 'Python Version from PEP 621 TOML',
+        description,
+        parameters: queryParams({
+          name: 'tomlFilePath',
+          example:
+            'https://raw.githubusercontent.com/numpy/numpy/main/pyproject.toml',
+          required: true,
+        }),
       },
-      staticPreview: this.render({ requiresPythonString: '>=3.9' }),
-      documentation,
     },
-  ]
+  }
 
   static defaultBadgeData = { label: 'python' }