migrate some services from examples to openApi

chris48s · Dec 29, 2023 · 369d082 · 369d082
1 parent 4ba8617
commit 369d082
Show file tree

Hide file tree

Showing 11 changed files with 187 additions and 212 deletions.
diff --git 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',

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

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

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

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

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

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