migrate some services from examples to openApi (badges#9904)

services/github/github-commits-difference.service.js

@@ -1,4 +1,5 @@
 import Joi from 'joi'
+import { pathParam, queryParam } from '../index.js'
 import { metric } from '../text-formatters.js'
 import { nonNegativeInteger } from '../validators.js'
 import { GithubAuthV3Service } from './github-auth-service.js'
@@ -19,23 +20,20 @@ export default class GithubCommitsDifference extends GithubAuthV3Service {
     queryParamSchema,
   }
 
-  static examples = [
-    {
-      title: 'GitHub commits difference between two branches/tags/commits',
-      namedParams: {
-        user: 'microsoft',
-        repo: 'vscode',
+  static openApi = {
+    '/github/commits-difference/{user}/{repo}': {
+      get: {
+        summary: 'GitHub commits difference between two branches/tags/commits',
+        description: documentation,
+        parameters: [
+          pathParam({ name: 'user', example: 'microsoft' }),
+          pathParam({ name: 'repo', example: 'vscode' }),
+          queryParam({ name: 'base', example: '1.60.0', required: true }),
+          queryParam({ name: 'head', example: '82f2db7', required: true }),
+        ],
       },
-      queryParams: {
-        base: '1.60.0',
-        head: '82f2db7',
-      },
-      staticPreview: this.render({
-        commitCount: 9227,
-      }),
-      documentation,
     },
-  ]
+  }
 
   static defaultBadgeData = { label: 'commits difference', namedLogo: 'github' }
 

services/github/github-directory-file-count.service.js

@@ -1,26 +1,9 @@
 import Joi from 'joi'
 import gql from 'graphql-tag'
 import { metric } from '../text-formatters.js'
-import { InvalidParameter } from '../index.js'
+import { InvalidParameter, pathParam, queryParam } from '../index.js'
 import { GithubAuthV4Service } from './github-auth-service.js'
-import {
-  documentation as commonDocumentation,
-  transformErrors,
-} from './github-helpers.js'
-
-const documentation = `${commonDocumentation}
-<p>
-  <b>Note:</b><br>
-  1. Parameter <code>type</code> accepts either <code>file</code> or <code>dir</code> value. Passing any other value will result in an error.<br>
-  2. Parameter <code>extension</code> accepts file extension without a leading dot.
-     For instance for <code>.js</code> extension pass <code>js</code>.
-     Only single <code>extension</code> value can be specified.
-     <code>extension</code> is applicable for <code>type</code> <code>file</code> only.
-     Passing it either without <code>type</code> or along with <code>type</code> <code>dir</code> will result in an error.<br>
-  3. GitHub API has an upper limit of 1,000 files for a directory.
-     In case a directory contains files above the limit, a badge might present inaccurate information.<br>
-</p>
-`
+import { documentation, transformErrors } from './github-helpers.js'
 
 const schema = Joi.object({
   data: Joi.object({
@@ -39,11 +22,18 @@ const schema = Joi.object({
   }).required(),
 }).required()
 
+const typeEnum = ['dir', 'file']
+
 const queryParamSchema = Joi.object({
-  type: Joi.any().valid('dir', 'file'),
+  type: Joi.any().valid(...typeEnum),
   extension: Joi.string(),
 })
 
+const typeDocs =
+  'Entity to count: directories or files. If not specified, both files and directories are counted. GitHub API has an upper limit of 1,000 files for a directory. If a directory contains files above the limit, the badge will show an inaccurate count.'
+const extensionDocs =
+  'Filter to files of type. Specify the extension without a leading dot. For instance for `.js` extension pass `js`. This param is only applicable if type is `file`'
+
 export default class GithubDirectoryFileCount extends GithubAuthV4Service {
   static category = 'size'
 
@@ -53,62 +43,51 @@ export default class GithubDirectoryFileCount extends GithubAuthV4Service {
     queryParamSchema,
   }
 
-  static examples = [
-    {
-      title: 'GitHub repo file count',
-      pattern: ':user/:repo',
-      namedParams: { user: 'badges', repo: 'shields' },
-      staticPreview: this.render({ count: 20 }),
-      documentation,
-    },
-    {
-      title: 'GitHub repo file count (custom path)',
-      pattern: ':user/:repo/:path',
-      namedParams: { user: 'badges', repo: 'shields', path: 'services' },
-      staticPreview: this.render({ count: 10 }),
-      documentation,
-    },
-    {
-      title: 'GitHub repo directory count',
-      pattern: ':user/:repo',
-      namedParams: { user: 'badges', repo: 'shields' },
-      queryParams: { type: 'dir' },
-      staticPreview: this.render({ count: 8 }),
-      documentation,
-    },
-    {
-      title: 'GitHub repo directory count (custom path)',
-      pattern: ':user/:repo/:path',
-      namedParams: { user: 'badges', repo: 'shields', path: 'services' },
-      queryParams: { type: 'dir' },
-      staticPreview: this.render({ count: 8 }),
-      documentation,
-    },
-    {
-      title: 'GitHub repo file count (file type)',
-      pattern: ':user/:repo',
-      namedParams: { user: 'badges', repo: 'shields' },
-      queryParams: { type: 'file' },
-      staticPreview: this.render({ count: 2 }),
-      documentation,
-    },
-    {
-      title: 'GitHub repo file count (custom path & file type)',
-      pattern: ':user/:repo/:path',
-      namedParams: { user: 'badges', repo: 'shields', path: 'services' },
-      queryParams: { type: 'file' },
-      staticPreview: this.render({ count: 2 }),
-      documentation,
+  static openApi = {
+    '/github/directory-file-count/{user}/{repo}': {
+      get: {
+        summary: 'GitHub repo file or directory count',
+        description: documentation,
+        parameters: [
+          pathParam({ name: 'user', example: 'badges' }),
+          pathParam({ name: 'repo', example: 'shields' }),
+          queryParam({
+            name: 'type',
+            example: 'file',
+            schema: { type: 'string', enum: typeEnum },
+            description: typeDocs,
+          }),
+          queryParam({
+            name: 'extension',
+            example: 'js',
+            description: extensionDocs,
+          }),
+        ],
+      },
     },
-    {
-      title: 'GitHub repo file count (file extension)',
-      pattern: ':user/:repo/:path',
-      namedParams: { user: 'badges', repo: 'shields', path: 'services' },
-      queryParams: { type: 'file', extension: 'js' },
-      staticPreview: this.render({ count: 1 }),
-      documentation,
+    '/github/directory-file-count/{user}/{repo}/{path}': {
+      get: {
+        summary: 'GitHub repo file or directory count (in path)',
+        description: documentation,
+        parameters: [
+          pathParam({ name: 'user', example: 'badges' }),
+          pathParam({ name: 'repo', example: 'shields' }),
+          pathParam({ name: 'path', example: 'services' }),
+          queryParam({
+            name: 'type',
+            example: 'file',
+            schema: { type: 'string', enum: typeEnum },
+            description: typeDocs,
+          }),
+          queryParam({
+            name: 'extension',
+            example: 'js',
+            description: extensionDocs,
+          }),
+        ],
+      },
     },
-  ]
+  }
 
   static defaultBadgeData = { color: 'blue', label: 'files' }
 

services/github/github-discussions-custom-search.service.js

@@ -1,15 +1,15 @@
 import gql from 'graphql-tag'
 import Joi from 'joi'
+import { pathParam, queryParam } from '../index.js'
 import { metric } from '../text-formatters.js'
 import { nonNegativeInteger } from '../validators.js'
 import { GithubAuthV4Service } from './github-auth-service.js'
 import { documentation, transformErrors } from './github-helpers.js'
 
 const discussionsSearchDocs = `
-For a full list of available filters and allowed values that can be used in the <code>query</code>,
+For a full list of available filters and allowed values,
 see GitHub's documentation on
 [Searching discussions](https://docs.github.com/en/search-github/searching-on-github/searching-discussions).
-${documentation}
 `
 
 const discussionCountSchema = Joi.object({
@@ -56,21 +56,22 @@ class GithubDiscussionsSearch extends BaseGithubDiscussionsSearch {
     queryParamSchema,
   }
 
-  static examples = [
-    {
-      title: 'GitHub discussions custom search',
-      namedParams: {},
-      queryParams: {
-        query: 'repo:badges/shields is:answered answered-by:chris48s',
+  static openApi = {
+    '/github/discussions-search': {
+      get: {
+        summary: 'GitHub discussions custom search',
+        description: documentation,
+        parameters: [
+          queryParam({
+            name: 'query',
+            description: discussionsSearchDocs,
+            example: 'repo:badges/shields is:answered answered-by:chris48s',
+            required: true,
+          }),
+        ],
       },
-      staticPreview: {
-        label: 'query',
-        message: '2',
-        color: 'blue',
-      },
-      documentation: discussionsSearchDocs,
     },
-  ]
+  }
 
   async handle(namedParams, { query }) {
     const discussionCount = await this.fetch({ query })
@@ -85,24 +86,24 @@ class GithubRepoDiscussionsSearch extends BaseGithubDiscussionsSearch {
     queryParamSchema,
   }
 
-  static examples = [
-    {
-      title: 'GitHub discussions custom search in repo',
-      namedParams: {
-        user: 'badges',
-        repo: 'shields',
-      },
-      queryParams: {
-        query: 'is:answered answered-by:chris48s',
+  static openApi = {
+    '/github/discussions-search/{user}/{repo}': {
+      get: {
+        summary: 'GitHub discussions custom search in repo',
+        description: documentation,
+        parameters: [
+          pathParam({ name: 'user', example: 'badges' }),
+          pathParam({ name: 'repo', example: 'shields' }),
+          queryParam({
+            name: 'query',
+            description: discussionsSearchDocs,
+            example: 'is:answered answered-by:chris48s',
+            required: true,
+          }),
+        ],
       },
-      staticPreview: {
-        label: 'query',
-        message: '2',
-        color: 'blue',
-      },
-      documentation: discussionsSearchDocs,
     },
-  ]
+  }
 
   async handle({ user, repo }, { query }) {
     query = `repo:${user}/${repo} ${query}`

services/github/github-issues-search.service.js

@@ -1,16 +1,15 @@
 import gql from 'graphql-tag'
 import Joi from 'joi'
+import { pathParam, queryParam } from '../index.js'
 import { metric } from '../text-formatters.js'
 import { nonNegativeInteger } from '../validators.js'
 import { GithubAuthV4Service } from './github-auth-service.js'
 import { documentation, transformErrors } from './github-helpers.js'
 
 const issuesSearchDocs = `
-For a full list of available filters and allowed values that can be used in the <code>query</code>,
+For a full list of available filters and allowed values,
 see GitHub's documentation on
 [Searching issues and pull requests](https://docs.github.com/en/search-github/searching-on-github/searching-issues-and-pull-requests)
-
-${documentation}
 `
 
 const issueCountSchema = Joi.object({
@@ -57,21 +56,23 @@ class GithubIssuesSearch extends BaseGithubIssuesSearch {
     queryParamSchema,
   }
 
-  static examples = [
-    {
-      title: 'GitHub issue custom search',
-      namedParams: {},
-      queryParams: {
-        query: 'repo:badges/shields is:closed label:bug author:app/sentry-io',
-      },
-      staticPreview: {
-        label: 'query',
-        message: '10',
-        color: 'blue',
+  static openApi = {
+    '/github/issues-search': {
+      get: {
+        summary: 'GitHub issue custom search',
+        description: documentation,
+        parameters: [
+          queryParam({
+            name: 'query',
+            description: issuesSearchDocs,
+            example:
+              'repo:badges/shields is:closed label:bug author:app/sentry-io',
+            required: true,
+          }),
+        ],
       },
-      documentation: issuesSearchDocs,
     },
-  ]
+  }
 
   async handle(namedParams, { query }) {
     const issueCount = await this.fetch({ query })
@@ -86,24 +87,24 @@ class GithubRepoIssuesSearch extends BaseGithubIssuesSearch {
     queryParamSchema,
   }
 
-  static examples = [
-    {
-      title: 'GitHub issue custom search in repo',
-      namedParams: {
-        user: 'badges',
-        repo: 'shields',
+  static openApi = {
+    '/github/issues-search/{user}/{repo}': {
+      get: {
+        summary: 'GitHub issue custom search in repo',
+        description: documentation,
+        parameters: [
+          pathParam({ name: 'user', example: 'badges' }),
+          pathParam({ name: 'repo', example: 'shields' }),
+          queryParam({
+            name: 'query',
+            description: issuesSearchDocs,
+            example: 'is:closed label:bug author:app/sentry-io',
+            required: true,
+          }),
+        ],
       },
-      queryParams: {
-        query: 'is:closed label:bug author:app/sentry-io',
-      },
-      staticPreview: {
-        label: 'query',
-        message: '10',
-        color: 'blue',
-      },
-      documentation: issuesSearchDocs,
     },
-  ]
+  }
 
   async handle({ user, repo }, { query }) {
     query = `repo:${user}/${repo} ${query}`