migrate some services from examples to openApi

badges · Jan 29, 2024 · b80dfd2 · b80dfd2
1 parent 59d101e
commit b80dfd2
Show file tree

Hide file tree

Showing 5 changed files with 146 additions and 86 deletions.
diff --git a/services/docker/docker-cloud-automated.service.js b/services/docker/docker-cloud-automated.service.js
@@ -1,4 +1,4 @@
-import { BaseJsonService } from '../index.js'
+import { BaseJsonService, pathParams } from '../index.js'
 import { dockerBlue, buildDockerUrl } from './docker-helpers.js'
 import { fetchBuild } from './docker-cloud-common-fetch.js'
 
@@ -13,17 +13,23 @@ export default class DockerCloudAutomatedBuild extends BaseJsonService {
     isRequired: false,
   }
 
-  static examples = [
-    {
-      title: 'Docker Cloud Automated build',
-      documentation: '<p>For the new Docker Hub (https://cloud.docker.com)</p>',
-      namedParams: {
-        user: 'jrottenberg',
-        repo: 'ffmpeg',
+  static openApi = {
+    '/docker/cloud/automated/{user}/{repo}': {
+      get: {
+        summary: 'Docker Cloud Automated build',
+        parameters: pathParams(
+          {
+            name: 'user',
+            example: 'jrottenberg',
+          },
+          {
+            name: 'repo',
+            example: 'ffmpeg',
+          },
+        ),
       },
-      staticPreview: this.render({ buildSettings: ['test'] }),
     },
-  ]
+  }
 
   static _cacheLength = 14400
 

diff --git a/services/docker/docker-cloud-build.service.js b/services/docker/docker-cloud-build.service.js
@@ -1,4 +1,4 @@
-import { BaseJsonService, NotFound } from '../index.js'
+import { BaseJsonService, NotFound, pathParams } from '../index.js'
 import { dockerBlue, buildDockerUrl } from './docker-helpers.js'
 import { fetchBuild } from './docker-cloud-common-fetch.js'
 
@@ -13,17 +13,23 @@ export default class DockerCloudBuild extends BaseJsonService {
     isRequired: false,
   }
 
-  static examples = [
-    {
-      title: 'Docker Cloud Build Status',
-      documentation: '<p>For the new Docker Hub (https://cloud.docker.com)</p>',
-      namedParams: {
-        user: 'jrottenberg',
-        repo: 'ffmpeg',
+  static openApi = {
+    '/docker/cloud/build/{user}/{repo}': {
+      get: {
+        summary: 'Docker Cloud Build Status',
+        parameters: pathParams(
+          {
+            name: 'user',
+            example: 'jrottenberg',
+          },
+          {
+            name: 'repo',
+            example: 'ffmpeg',
+          },
+        ),
       },
-      staticPreview: this.render({ state: 'Success' }),
     },
-  ]
+  }
 
   static defaultBadgeData = { label: 'docker build' }
 

diff --git a/services/docker/docker-helpers.js b/services/docker/docker-helpers.js
@@ -3,23 +3,25 @@ import Joi from 'joi'
 import { NotFound } from '../index.js'
 const dockerBlue = '066da5'
 
+const archEnum = [
+  'amd64',
+  'arm',
+  'arm64',
+  's390x',
+  '386',
+  'ppc64',
+  'ppc64le',
+  'wasm',
+  'mips',
+  'mipsle',
+  'mips64',
+  'mips64le',
+  'riscv64',
+]
+
 // Valid architecture values: https://golang.org/doc/install/source#environment (GOARCH)
 const archSchema = Joi.alternatives(
-  Joi.string().valid(
-    'amd64',
-    'arm',
-    'arm64',
-    's390x',
-    '386',
-    'ppc64',
-    'ppc64le',
-    'wasm',
-    'mips',
-    'mipsle',
-    'mips64',
-    'mips64le',
-    'riscv64',
-  ),
+  Joi.string().valid(...archEnum),
   Joi.number().valid(386).cast('string'),
 )
 
@@ -76,6 +78,7 @@ function getDigestSemVerMatches({ data, digest }) {
 }
 
 export {
+  archEnum,
   archSchema,
   dockerBlue,
   buildDockerUrl,

diff --git a/services/docker/docker-size.service.js b/services/docker/docker-size.service.js
@@ -2,8 +2,9 @@ import Joi from 'joi'
 import prettyBytes from 'pretty-bytes'
 import { nonNegativeInteger } from '../validators.js'
 import { latest } from '../version.js'
-import { BaseJsonService, NotFound } from '../index.js'
+import { BaseJsonService, NotFound, pathParams, queryParams } from '../index.js'
 import {
+  archEnum,
   archSchema,
   buildDockerUrl,
   getDockerHubUser,
@@ -38,11 +39,29 @@ const pagedSchema = Joi.object({
   ),
 }).required()
 
+const sortEnum = ['date', 'semver']
+
 const queryParamSchema = Joi.object({
-  sort: Joi.string().valid('date', 'semver').default('date'),
+  sort: Joi.string()
+    .valid(...sortEnum)
+    .default('date'),
   arch: archSchema,
 }).required()
 
+const openApiQueryParams = queryParams(
+  {
+    name: 'sort',
+    example: 'semver',
+    schema: { type: 'string', enum: sortEnum },
+    description: 'If not specified, the default is `date`',
+  },
+  {
+    name: 'arch',
+    example: 'amd64',
+    schema: { type: 'string', enum: archEnum },
+  },
+)
+
 // If user provided the arch parameter,
 // check if any of the returned images has an architecture matching the arch parameter provided.
 // If yes, return the size of the image with this arch.
@@ -73,36 +92,33 @@ export default class DockerSize extends BaseJsonService {
     isRequired: false,
   }
 
-  static examples = [
-    {
-      title: 'Docker Image Size (latest by date)',
-      pattern: ':user/:repo',
-      namedParams: { user: 'fedora', repo: 'apache' },
-      queryParams: { sort: 'date' },
-      staticPreview: this.render({ size: 126000000 }),
-    },
-    {
-      title: 'Docker Image Size (latest semver)',
-      pattern: ':user/:repo',
-      namedParams: { user: 'fedora', repo: 'apache' },
-      queryParams: { sort: 'semver' },
-      staticPreview: this.render({ size: 136000000 }),
-    },
-    {
-      title:
-        'Docker Image Size with architecture (latest by date/latest semver)',
-      pattern: ':user/:repo',
-      namedParams: { user: 'library', repo: 'mysql' },
-      queryParams: { sort: 'date', arch: 'amd64' },
-      staticPreview: this.render({ size: 146000000 }),
+  static openApi = {
+    '/docker/image-size/{user}/{repo}': {
+      get: {
+        summary: 'Docker Image Size',
+        parameters: [
+          ...pathParams(
+            { name: 'user', example: 'fedora' },
+            { name: 'repo', example: 'apache' },
+          ),
+          ...openApiQueryParams,
+        ],
+      },
     },
-    {
-      title: 'Docker Image Size (tag)',
-      pattern: ':user/:repo/:tag',
-      namedParams: { user: 'fedora', repo: 'apache', tag: 'latest' },
-      staticPreview: this.render({ size: 103000000 }),
+    '/docker/image-size/{user}/{repo}/{tag}': {
+      get: {
+        summary: 'Docker Image Size (tag)',
+        parameters: [
+          ...pathParams(
+            { name: 'user', example: 'fedora' },
+            { name: 'repo', example: 'apache' },
+            { name: 'tag', example: 'latest' },
+          ),
+          ...openApiQueryParams,
+        ],
+      },
     },
-  ]
+  }
 
   static _cacheLength = 600
 

diff --git a/services/docker/docker-version.service.js b/services/docker/docker-version.service.js
@@ -1,8 +1,15 @@
 import Joi from 'joi'
 import { nonNegativeInteger } from '../validators.js'
 import { latest, renderVersionBadge } from '../version.js'
-import { BaseJsonService, NotFound, InvalidResponse } from '../index.js'
 import {
+  BaseJsonService,
+  NotFound,
+  InvalidResponse,
+  pathParams,
+  queryParams,
+} from '../index.js'
+import {
+  archEnum,
   archSchema,
   buildDockerUrl,
   getDockerHubUser,
@@ -26,11 +33,28 @@ const buildSchema = Joi.object({
   ),
 }).required()
 
+const sortEnum = ['date', 'semver']
+
 const queryParamSchema = Joi.object({
   sort: Joi.string().valid('date', 'semver').default('date'),
   arch: archSchema.default('amd64'),
 }).required()
 
+const openApiQueryParams = queryParams(
+  {
+    name: 'sort',
+    example: 'semver',
+    schema: { type: 'string', enum: sortEnum },
+    description: 'If not specified, the default is `date`',
+  },
+  {
+    name: 'arch',
+    example: 'amd64',
+    schema: { type: 'string', enum: archEnum },
+    description: 'If not specified, the default is `amd64`',
+  },
+)
+
 export default class DockerVersion extends BaseJsonService {
   static category = 'version'
   static route = { ...buildDockerUrl('v', true), queryParamSchema }
@@ -45,28 +69,33 @@ export default class DockerVersion extends BaseJsonService {
     isRequired: false,
   }
 
-  static examples = [
-    {
-      title: 'Docker Image Version (latest by date)',
-      pattern: ':user/:repo',
-      namedParams: { user: '_', repo: 'alpine' },
-      queryParams: { sort: 'date', arch: 'amd64' },
-      staticPreview: this.render({ version: '3.9.5' }),
+  static openApi = {
+    '/docker/v/{user}/{repo}': {
+      get: {
+        summary: 'Docker Image Version',
+        parameters: [
+          ...pathParams(
+            { name: 'user', example: '_' },
+            { name: 'repo', example: 'alpine' },
+          ),
+          ...openApiQueryParams,
+        ],
+      },
     },
-    {
-      title: 'Docker Image Version (latest semver)',
-      pattern: ':user/:repo',
-      namedParams: { user: '_', repo: 'alpine' },
-      queryParams: { sort: 'semver' },
-      staticPreview: this.render({ version: '3.11.3' }),
+    '/docker/v/{user}/{repo}/{tag}': {
+      get: {
+        summary: 'Docker Image Version (tag)',
+        parameters: [
+          ...pathParams(
+            { name: 'user', example: '_' },
+            { name: 'repo', example: 'alpine' },
+            { name: 'tag', example: '3.6' },
+          ),
+          ...openApiQueryParams,
+        ],
+      },
     },
-    {
-      title: 'Docker Image Version (tag latest semver)',
-      pattern: ':user/:repo/:tag',
-      namedParams: { user: '_', repo: 'alpine', tag: '3.6' },
-      staticPreview: this.render({ version: '3.6.5' }),
-    },
-  ]
+  }
 
   static defaultBadgeData = { label: 'version', color: 'blue' }