update website docs, migrate examples to openapi (#9612)

badges · Dec 2, 2023 · 1c073cb · 1c073cb
1 parent 9118ba8
commit 1c073cb
Show file tree

Hide file tree

Showing 4 changed files with 50 additions and 47 deletions.
diff --git a/services/nodeping/nodeping-status.service.js b/services/nodeping/nodeping-status.service.js
@@ -1,10 +1,10 @@
 import Joi from 'joi'
 import {
   queryParamSchema,
-  exampleQueryParams,
+  queryParams,
   renderWebsiteStatus,
 } from '../website-status.js'
-import { BaseJsonService } from '../index.js'
+import { BaseJsonService, pathParams } from '../index.js'
 
 const schema = Joi.array()
   .items(Joi.object().keys({ su: Joi.boolean() }))
@@ -24,14 +24,17 @@ export default class NodePingStatus extends BaseJsonService {
     queryParamSchema,
   }
 
-  static examples = [
-    {
-      title: 'NodePing status',
-      namedParams: { checkUuid: exampleCheckUuid },
-      queryParams: exampleQueryParams,
-      staticPreview: renderWebsiteStatus({ isUp: true }),
+  static openApi = {
+    '/nodeping/status/{checkUuid}': {
+      get: {
+        summary: 'NodePing status',
+        parameters: pathParams({
+          name: 'checkUuid',
+          example: exampleCheckUuid,
+        }).concat(queryParams),
+      },
     },
-  ]
+  }
 
   static defaultBadgeData = { label: 'status' }
 

diff --git a/services/nodeping/nodeping-uptime.service.js b/services/nodeping/nodeping-uptime.service.js
@@ -1,6 +1,6 @@
 import Joi from 'joi'
 import { colorScale } from '../color-formatters.js'
-import { BaseJsonService } from '../index.js'
+import { BaseJsonService, pathParams } from '../index.js'
 
 const colorFormatter = colorScale([99, 99.5, 100])
 
@@ -26,13 +26,17 @@ export default class NodePingUptime extends BaseJsonService {
 
   static route = { base: 'nodeping/uptime', pattern: ':checkUuid' }
 
-  static examples = [
-    {
-      title: 'NodePing uptime',
-      namedParams: { checkUuid: sampleCheckUuid },
-      staticPreview: this.render({ uptime: 99.999 }),
+  static openApi = {
+    '/nodeping/uptime/{checkUuid}': {
+      get: {
+        summary: 'NodePing uptime',
+        parameters: pathParams({
+          name: 'checkUuid',
+          example: sampleCheckUuid,
+        }),
+      },
     },
-  ]
+  }
 
   static defaultBadgeData = { label: 'uptime' }
 

diff --git a/services/website-status.js b/services/website-status.js
@@ -5,6 +5,7 @@
  */
 
 import Joi from 'joi'
+import { queryParams as qP } from './index.js'
 
 /**
  * Joi schema for validating query params.
@@ -20,17 +21,18 @@ const queryParamSchema = Joi.object({
 }).required()
 
 /**
- * Example query param object.
- * Contains up_message, down_message, up_color and down_color properties.
+ * Array of OpenAPI Parameter Objects describing the
+ * up_message, down_message, up_color and down_color
+ * query params
  *
- * @type {object}
+ * @type {Array.<module:core/base-service/openapi~OpenApiParam>}
  */
-const exampleQueryParams = {
-  up_message: 'online',
-  up_color: 'blue',
-  down_message: 'offline',
-  down_color: 'lightgrey',
-}
+const queryParams = qP(
+  { name: 'up_message', example: 'online' },
+  { name: 'up_color', example: 'blue' },
+  { name: 'down_message', example: 'offline' },
+  { name: 'down_color', example: 'lightgrey' },
+)
 
 /**
  * Creates a badge object that displays information about website status.
@@ -60,4 +62,4 @@ function renderWebsiteStatus({
   }
 }
 
-export { queryParamSchema, exampleQueryParams, renderWebsiteStatus }
+export { queryParamSchema, queryParams, renderWebsiteStatus }
diff --git a/services/website/website.service.js b/services/website/website.service.js
@@ -3,23 +3,16 @@ import emojic from 'emojic'
 import { optionalUrl } from '../validators.js'
 import {
   queryParamSchema,
-  exampleQueryParams,
+  queryParams as websiteQueryParams,
   renderWebsiteStatus,
 } from '../website-status.js'
-import { BaseService } from '../index.js'
+import { BaseService, queryParams } from '../index.js'
 import trace from '../../core/base-service/trace.js'
 
-const documentation = `
-The badge is of the form
-\`https://img.shields.io/website/PROTOCOL/URLREST.svg\`.
-
-The whole URL is obtained by concatenating the \`PROTOCOL\`
-(\`http\` or \`https\`, for example) with the
-\`URLREST\` (separating them with \`://\`).
-
+const description = `
 The existence of a specific path on the server can be checked by appending
 a path after the domain name, e.g.
-\`https://img.shields.io/website/http/www.website.com/path/to/page.html.svg\`.
+\`https://img.shields.io/website?url=http%3A//www.website.com/path/to/page.html\`.
 
 The messages and colors for the up and down states can also be customized.
 `
@@ -37,18 +30,19 @@ export default class Website extends BaseService {
     queryParamSchema: queryParamSchema.concat(urlQueryParamSchema),
   }
 
-  static examples = [
-    {
-      title: 'Website',
-      namedParams: {},
-      queryParams: {
-        ...exampleQueryParams,
-        ...{ url: 'https://shields.io' },
+  static openApi = {
+    '/website': {
+      get: {
+        summary: 'Website',
+        description,
+        parameters: queryParams({
+          name: 'url',
+          required: true,
+          example: 'https://shields.io',
+        }).concat(websiteQueryParams),
       },
-      staticPreview: renderWebsiteStatus({ isUp: true }),
-      documentation,
     },
-  ]
+  }
 
   static defaultBadgeData = {
     label: 'website',