migrate some services from examples to openApi (#9856)

2025-04-18 19:44:04 +03:00 · 2023-12-31 19:39:00 +00:00 · 2023-12-31 19:39:00 +00:00 · 8d7258b344
commit 8d7258b344
parent 66af65c9e2
11 changed files with 187 additions and 212 deletions
--- a/services/testspace/testspace-test-count.service.js
+++ b/services/testspace/testspace-test-count.service.js
@ -12,7 +12,7 @@ export default class TestspaceTestCount extends TestspaceBase {
  static openApi = {
    '/testspace/{metric}/{org}/{project}/{space}': {
      get: {
-        summary: 'Testspace tests',
+        summary: 'Testspace tests count',
        parameters: pathParams(
          {
            name: 'metric',
--- a/services/testspace/testspace-test-summary.service.js
+++ b/services/testspace/testspace-test-summary.service.js
@ -1,6 +1,8 @@
+import { pathParams } from '../index.js'
 import {
-  documentation,
+  documentation as description,
  testResultQueryParamSchema,
+  testResultOpenApiQueryParams,
  renderTestResultBadge,
 } from '../test-results.js'
 import TestspaceBase from './testspace-base.js'
@ -12,69 +14,22 @@ export default class TestspaceTests extends TestspaceBase {
    queryParamSchema: testResultQueryParamSchema,
  }

-  static examples = [
-    {
-      title: 'Testspace tests',
-      namedParams: {
-        org: 'swellaby',
-        project: 'swellaby:testspace-sample',
-        space: 'main',
+  static openApi = {
+    '/testspace/tests/{org}/{project}/{space}': {
+      get: {
+        summary: 'Testspace tests',
+        description,
+        parameters: [
+          ...pathParams(
+            { name: 'org', example: 'swellaby' },
+            { name: 'project', example: 'swellaby:testspace-sample' },
+            { name: 'space', example: 'main' },
+          ),
+          ...testResultOpenApiQueryParams,
+        ],
      },
-      queryParams: {
-        passed_label: 'passed',
-        failed_label: 'failed',
-        skipped_label: 'skipped',
-      },
-      staticPreview: renderTestResultBadge({
-        passed: 477,
-        failed: 2,
-        skipped: 0,
-        total: 479,
-        isCompact: false,
-      }),
-      documentation,
    },
-    {
-      title: 'Testspace tests (compact)',
-      namedParams: {
-        org: 'swellaby',
-        project: 'swellaby:testspace-sample',
-        space: 'main',
-      },
-      queryParams: {
-        compact_message: null,
-      },
-      staticPreview: renderTestResultBadge({
-        passed: 20,
-        failed: 1,
-        skipped: 1,
-        total: 22,
-        isCompact: true,
-      }),
-    },
-    {
-      title: 'Testspace tests with custom labels',
-      namedParams: {
-        org: 'swellaby',
-        project: 'swellaby:testspace-sample',
-        space: 'main',
-      },
-      queryParams: {
-        passed_label: 'good',
-        failed_label: 'bad',
-        skipped_label: 'n/a',
-      },
-      staticPreview: renderTestResultBadge({
-        passed: 20,
-        failed: 1,
-        skipped: 1,
-        total: 22,
-        passedLabel: 'good',
-        failedLabel: 'bad',
-        skippedLabel: 'n/a',
-      }),
-    },
-  ]
+  }

  async handle(
    { org, project, space },
--- a/services/twitch/twitch.service.js
+++ b/services/twitch/twitch.service.js
@ -1,4 +1,5 @@
 import Joi from 'joi'
+import { pathParams } from '../index.js'
 import TwitchBase from './twitch-base.js'

 const helixSchema = Joi.object({
@ -13,20 +14,17 @@ export default class TwitchStatus extends TwitchBase {
    pattern: ':user',
  }

-  static examples = [
-    {
-      title: 'Twitch Status',
-      namedParams: {
-        user: 'andyonthewings',
-      },
-      queryParams: { style: 'social' },
-      staticPreview: {
-        message: 'live',
-        color: 'red',
-        style: 'social',
+  static openApi = {
+    '/twitch/status/{user}': {
+      get: {
+        summary: 'Twitch Status',
+        parameters: pathParams({
+          name: 'user',
+          example: 'andyonthewings',
+        }),
      },
    },
-  ]
+  }

  static _cacheLength = 30

--- a/services/w3c/w3c-validation-helper.js
+++ b/services/w3c/w3c-validation-helper.js
@ -77,72 +77,20 @@ const getSchema = preset => {
  return schema.map(url => encodeURI(url)).join(' ')
 }

-const documentation = `
-  <style>
-    .box {
-      display: flex;
-      justify-content: space-between;
-    }
-    .note {
-      font-size: smaller;
-      text-align: left;
-    }
-  </style>
-  <p>
-    The W3C validation badge performs validation of the HTML, SVG, MathML, ITS, RDFa Lite, XHTML documents.
-    The badge uses the type property of each message found in the messages from the validation results to determine to be an error or warning.
-    The rules are as follows:
-    <ul class="note">
-      <li>info:  These messages are counted as warnings</li>
-      <li>error:  These messages are counted as errors</li>
-      <li>non-document-error: These messages are counted as errors</li>
-    </ul>
-  </p>
-  <p>
-    This badge relies on the <a target="_blank" href="https://validator.nu/">https://validator.nu/</a> service to perform the validation.
-    Please refer to <a target="_blank" href="https://about.validator.nu/">https://about.validator.nu/</a> for the full documentation and Terms of service.
-    The following are required from the consumer for the badge to function.
-    <ul class="note">
-      <li>
-        Path:
-        <ul>
-          <li>
-            parser: The parser that is used for validation. This is a passthru value to the service
-            <ul>
-              <li>default <i>(This will not pass a parser to the API and make the API choose the parser based on the validated content)</i></li>
-              <li>html <i>(HTML)</i></li>
-              <li>xml <i>(XML; don’t load external entities)</i></li>
-              <li>xmldtd <i>(XML; load external entities)</i></li>
-            </ul>
-          </li>
-        </ul>
-      </li>
-      <li>
-        Query string:
-        <ul>
-          <li>
-            targetUrl (Required): This is the path for the document to be validated
-          </li>
-          <li>
-            preset (Optional can be left as blank): This is used to determine the schema for the document to be valdiated against.
-            The following are the allowed values
-            <ul>
-              <li>HTML, SVG 1.1, MathML 3.0</li>
-              <li>HTML, SVG 1.1, MathML 3.0, ITS 2.0</li>
-              <li>HTML, SVG 1.1, MathML 3.0, RDFa Lite 1.1</li>
-              <li>HTML 4.01 Strict, URL / XHTML 1.0 Strict, URL</li>
-              <li>HTML 4.01 Transitional, URL / XHTML 1.0 Transitional, URL</li>
-              <li>HTML 4.01 Frameset, URL / XHTML 1.0 Frameset, URL</li>
-              <li>XHTML, SVG 1.1, MathML 3.0</li>
-              <li>XHTML, SVG 1.1, MathML 3.0, RDFa Lite 1.1</li>
-              <li>XHTML 1.0 Strict, URL, Ruby, SVG 1.1, MathML 3.0</li>
-              <li>SVG 1.1, URL, XHTML, MathML 3.0</li>        
-            </ul>
-          </li>
-        </ul>
-      </li>
-    </ul>
-  </p>
+const description = `<p>
+  The W3C validation badge performs validation of the HTML, SVG, MathML, ITS, RDFa Lite, XHTML documents.
+  The badge uses the type property of each message found in the messages from the validation results to determine to be an error or warning.
+  The rules are as follows:
+  <ul>
+    <li>info:  These messages are counted as warnings</li>
+    <li>error:  These messages are counted as errors</li>
+    <li>non-document-error: These messages are counted as errors</li>
+  </ul>
+</p>
+<p>
+  This badge relies on the <a target="_blank" href="https://validator.nu/">https://validator.nu/</a> service to perform the validation.
+  Please refer to <a target="_blank" href="https://about.validator.nu/">https://about.validator.nu/</a> for the full documentation and Terms of service.
+</p>
 `

-export { documentation, presetRegex, getColor, getMessage, getSchema }
+export { description, presetRegex, getColor, getMessage, getSchema }
--- a/services/w3c/w3c-validation.service.js
+++ b/services/w3c/w3c-validation.service.js
@ -1,8 +1,8 @@
 import Joi from 'joi'
 import { optionalUrl } from '../validators.js'
-import { BaseJsonService, NotFound } from '../index.js'
+import { BaseJsonService, NotFound, pathParam, queryParam } from '../index.js'
 import {
-  documentation,
+  description,
  presetRegex,
  getColor,
  getMessage,
@ -29,6 +29,13 @@ const queryParamSchema = Joi.object({
  preset: Joi.string().regex(presetRegex).allow(''),
 }).required()

+const parserDescription = `The parser that is used for validation. This is a passthru value to the service
+- \`default\`: This will not pass a parser to the API and make the API choose the parser based on the validated content
+- \`html\`: HTML
+- \`xml\`: XML (don't load external entities)
+- \`xmldtd\`: XML (load external entities)
+`
+
 export default class W3cValidation extends BaseJsonService {
  static category = 'analysis'

@ -38,18 +45,49 @@ export default class W3cValidation extends BaseJsonService {
    queryParamSchema,
  }

-  static examples = [
-    {
-      title: 'W3C Validation',
-      namedParams: { parser: 'html' },
-      queryParams: {
-        targetUrl: 'https://validator.nu/',
-        preset: 'HTML, SVG 1.1, MathML 3.0',
+  static openApi = {
+    '/w3c-validation/{parser}': {
+      get: {
+        summary: 'W3C Validation',
+        description,
+        parameters: [
+          pathParam({
+            name: 'parser',
+            example: 'html',
+            schema: { type: 'string', enum: this.getEnum('parser') },
+            description: parserDescription,
+          }),
+          queryParam({
+            name: 'targetUrl',
+            example: 'https://validator.nu/',
+            required: true,
+            description: 'URL of the document to be validate',
+          }),
+          queryParam({
+            name: 'preset',
+            example: 'HTML, SVG 1.1, MathML 3.0',
+            description:
+              'This is used to determine the schema for the document to be valdiated against.',
+            schema: {
+              type: 'string',
+              enum: [
+                'HTML, SVG 1.1, MathML 3.0',
+                'HTML, SVG 1.1, MathML 3.0, ITS 2.0',
+                'HTML, SVG 1.1, MathML 3.0, RDFa Lite 1.1',
+                'HTML 4.01 Strict, URL / XHTML 1.0 Strict, URL',
+                'HTML 4.01 Transitional, URL / XHTML 1.0 Transitional, URL',
+                'HTML 4.01 Frameset, URL / XHTML 1.0 Frameset, URL',
+                'XHTML, SVG 1.1, MathML 3.0',
+                'XHTML, SVG 1.1, MathML 3.0, RDFa Lite 1.1',
+                'XHTML 1.0 Strict, URL, Ruby, SVG 1.1, MathML 3.0',
+                'SVG 1.1, URL, XHTML, MathML 3.0',
+              ],
+            },
+          }),
+        ],
      },
-      staticPreview: this.render({ messageTypes: {} }),
-      documentation,
    },
-  ]
+  }

  static defaultBadgeData = {
    label: 'w3c',
--- a/services/weblate/weblate-base.js
+++ b/services/weblate/weblate-base.js
@ -3,6 +3,8 @@ import { BaseJsonService } from '../index.js'
 import { optionalUrl } from '../validators.js'

 export const defaultServer = 'https://hosted.weblate.org'
+export const description =
+  'Weblate is an web-based tool for translation and internationalization'

 export default class WeblateBase extends BaseJsonService {
  static queryParamSchema = Joi.object({
--- a/services/weblate/weblate-component-license.service.js
+++ b/services/weblate/weblate-component-license.service.js
@ -1,5 +1,6 @@
 import Joi from 'joi'
-import WeblateBase, { defaultServer } from './weblate-base.js'
+import { pathParam, queryParam } from '../index.js'
+import WeblateBase, { defaultServer, description } from './weblate-base.js'

 const schema = Joi.object({
  license: Joi.string().required(),
@ -17,15 +18,19 @@ export default class WeblateComponentLicense extends WeblateBase {
    queryParamSchema: this.queryParamSchema,
  }

-  static examples = [
-    {
-      title: 'Weblate component license',
-      namedParams: { project: 'godot-engine', component: 'godot' },
-      queryParams: { server: defaultServer },
-      staticPreview: this.render({ license: 'MIT' }),
-      keywords: ['i18n', 'translation', 'internationalization'],
+  static openApi = {
+    '/weblate/l/{project}/{component}': {
+      get: {
+        summary: 'Weblate component license',
+        description,
+        parameters: [
+          pathParam({ name: 'project', example: 'godot-engine' }),
+          pathParam({ name: 'component', example: 'godot' }),
+          queryParam({ name: 'server', example: defaultServer }),
+        ],
+      },
    },
-  ]
+  }

  static defaultBadgeData = { label: 'license', color: 'informational' }

--- a/services/weblate/weblate-entities.service.js
+++ b/services/weblate/weblate-entities.service.js
@ -1,7 +1,8 @@
 import Joi from 'joi'
+import { pathParam, queryParam } from '../index.js'
 import { nonNegativeInteger } from '../validators.js'
 import { metric } from '../text-formatters.js'
-import WeblateBase, { defaultServer } from './weblate-base.js'
+import WeblateBase, { defaultServer, description } from './weblate-base.js'

 const schema = Joi.object({
  count: nonNegativeInteger,
@ -16,15 +17,22 @@ export default class WeblateEntities extends WeblateBase {
    queryParamSchema: this.queryParamSchema,
  }

-  static examples = [
-    {
-      title: 'Weblate entities',
-      namedParams: { type: 'projects' },
-      queryParams: { server: defaultServer },
-      staticPreview: this.render({ type: 'projects', count: 533 }),
-      keywords: ['i18n', 'internationalization'],
+  static openApi = {
+    '/weblate/{type}': {
+      get: {
+        summary: 'Weblate entities',
+        description,
+        parameters: [
+          pathParam({
+            name: 'type',
+            example: 'projects',
+            schema: { type: 'string', enum: this.getEnum('type') },
+          }),
+          queryParam({ name: 'server', example: defaultServer }),
+        ],
+      },
    },
-  ]
+  }

  static _cacheLength = 600

--- a/services/weblate/weblate-project-translated-percentage.service.js
+++ b/services/weblate/weblate-project-translated-percentage.service.js
@ -1,6 +1,7 @@
 import Joi from 'joi'
+import { pathParam, queryParam } from '../index.js'
 import { colorScale } from '../color-formatters.js'
-import WeblateBase, { defaultServer } from './weblate-base.js'
+import WeblateBase, { defaultServer, description } from './weblate-base.js'

 const schema = Joi.object({
  translated_percent: Joi.number().required(),
@ -19,15 +20,18 @@ export default class WeblateProjectTranslatedPercentage extends WeblateBase {
    queryParamSchema: this.queryParamSchema,
  }

-  static examples = [
-    {
-      title: 'Weblate project translated',
-      namedParams: { project: 'godot-engine' },
-      queryParams: { server: defaultServer },
-      staticPreview: this.render({ translatedPercent: 20.5 }),
-      keywords: ['i18n', 'translation', 'internationalization'],
+  static openApi = {
+    '/weblate/progress/{project}': {
+      get: {
+        summary: 'Weblate project translated',
+        description,
+        parameters: [
+          pathParam({ name: 'project', example: 'godot-engine' }),
+          queryParam({ name: 'server', example: defaultServer }),
+        ],
+      },
    },
-  ]
+  }

  static _cacheLength = 600

--- a/services/weblate/weblate-user-statistic.service.js
+++ b/services/weblate/weblate-user-statistic.service.js
@ -1,7 +1,8 @@
 import Joi from 'joi'
+import { pathParam, queryParam } from '../index.js'
 import { nonNegativeInteger } from '../validators.js'
 import { metric } from '../text-formatters.js'
-import WeblateBase, { defaultServer } from './weblate-base.js'
+import WeblateBase, { defaultServer, description } from './weblate-base.js'

 const schema = Joi.object({
  translated: nonNegativeInteger,
@ -29,15 +30,23 @@ export default class WeblateUserStatistic extends WeblateBase {
    queryParamSchema: this.queryParamSchema,
  }

-  static examples = [
-    {
-      title: 'Weblate user statistic',
-      namedParams: { statistic: 'translations', user: 'nijel' },
-      queryParams: { server: defaultServer },
-      staticPreview: this.render({ statistic: 'translations', count: 30585 }),
-      keywords: ['i18n', 'internationalization'],
+  static openApi = {
+    '/weblate/{statistic}/{user}': {
+      get: {
+        summary: 'Weblate user statistic',
+        description,
+        parameters: [
+          pathParam({
+            name: 'statistic',
+            example: 'translations',
+            schema: { type: 'string', enum: this.getEnum('statistic') },
+          }),
+          pathParam({ name: 'user', example: 'nijel' }),
+          queryParam({ name: 'server', example: defaultServer }),
+        ],
+      },
    },
-  ]
+  }

  static _cacheLength = 600

--- a/services/whatpulse/whatpulse.service.js
+++ b/services/whatpulse/whatpulse.service.js
@ -3,7 +3,7 @@ import dayjs from 'dayjs'
 import calendar from 'dayjs/plugin/calendar.js'
 import duration from 'dayjs/plugin/duration.js'
 import relativeTime from 'dayjs/plugin/relativeTime.js'
-import { BaseJsonService } from '../index.js'
+import { BaseJsonService, pathParam, queryParam } from '../index.js'
 import { metric as formatMetric, ordinalNumber } from '../text-formatters.js'
 dayjs.extend(calendar)
 dayjs.extend(duration)
@ -37,29 +37,37 @@ export default class WhatPulse extends BaseJsonService {
    queryParamSchema,
  }

-  static examples = [
-    {
-      title: 'WhatPulse user metric',
-      namedParams: { metric: 'keys', userType: 'user', id: '179734' },
-      staticPreview: this.render({
-        metric: 'keys',
-        metricValue: '21G',
-      }),
-    },
-    {
-      title: 'WhatPulse team metric - rank',
-      namedParams: {
-        metric: 'upload',
-        userType: 'team',
-        id: 'dutch power cows',
+  static openApi = {
+    '/whatpulse/{metric}/{userType}/{id}': {
+      get: {
+        summary: 'WhatPulse',
+        parameters: [
+          pathParam({
+            name: 'metric',
+            example: 'keys',
+            schema: { type: 'string', enum: this.getEnum('metric') },
+          }),
+          pathParam({
+            name: 'userType',
+            example: 'team',
+            schema: { type: 'string', enum: this.getEnum('userType') },
+          }),
+          pathParam({
+            name: 'id',
+            example: '179734',
+            description:
+              'Either a user ID (e.g: `179734`) or a group ID (e.g: `dutch power cows`)',
+          }),
+          queryParam({
+            name: 'rank',
+            description: 'show rank instead of value',
+            example: null,
+            schema: { type: 'boolean' },
+          }),
+        ],
      },
-      queryParams: { rank: null },
-      staticPreview: this.render({
-        metric: 'upload',
-        metricValue: '1ˢᵗ',
-      }),
    },
-  ]
+  }

  static defaultBadgeData = { label: 'whatpulse' }