migrate examples to openApi part 14; affects [azuredevops discord net…

…lify opencollective pub ros visualstudio] (badges#9560)

* migrate some services from examples to openApi

* migrate pub version

* improve pub descriptions

services/azure-devops/azure-devops-release.service.js

@@ -1,8 +1,8 @@
 import { renderBuildStatusBadge } from '../build-status.js'
-import { BaseSvgScrapingService } from '../index.js'
-import { keywords, fetch } from './azure-devops-helpers.js'
+import { BaseSvgScrapingService, pathParams } from '../index.js'
+import { fetch } from './azure-devops-helpers.js'
 
-const documentation = `
+const description = `
 To obtain your own badge, you need to get 4 pieces of information:
 \`ORGANIZATION\`, \`PROJECT_ID\`, \`DEFINITION_ID\` and \`ENVIRONMENT_ID\`.
 
@@ -25,20 +25,33 @@ export default class AzureDevOpsRelease extends BaseSvgScrapingService {
  pattern: ':organization/:projectId/:definitionId/:environmentId',
  }
 
- static examples = [
- {
- title: 'Azure DevOps releases',
- namedParams: {
- organization: 'totodem',
- projectId: '8cf3ec0e-d0c2-4fcd-8206-ad204f254a96',
- definitionId: '1',
- environmentId: '1',
+ static openApi = {
+ '/azure-devops/release/{organization}/{projectId}/{definitionId}/{environmentId}':
+ {
+ get: {
+ summary: 'Azure DevOps releases',
+ description,
+ parameters: pathParams(
+ {
+ name: 'organization',
+ example: 'totodem',
+ },
+ {
+ name: 'projectId',
+ example: '8cf3ec0e-d0c2-4fcd-8206-ad204f254a96',
+ },
+ {
+ name: 'definitionId',
+ example: '1',
+ },
+ {
+ name: 'environmentId',
+ example: '1',
+ },
+ ),
+ },
  },
- staticPreview: renderBuildStatusBadge({ status: 'succeeded' }),
- keywords,
- documentation,
- },
- ]
+ }
 
  static defaultBadgeData = { label: 'deployment' }
 

services/discord/discord.service.js

@@ -1,12 +1,12 @@
 import Joi from 'joi'
 import { nonNegativeInteger } from '../validators.js'
-import { BaseJsonService } from '../index.js'
+import { BaseJsonService, pathParams } from '../index.js'
 
 const schema = Joi.object({
  presence_count: nonNegativeInteger,
 }).required()
 
-const documentation = `
+const description = `
 <p>
  The Discord badge requires the <code>SERVER ID</code> in order access the Discord JSON API.
 </p>
@@ -36,14 +36,18 @@ export default class Discord extends BaseJsonService {
  isRequired: false,
  }
 
- static examples = [
- {
- title: 'Discord',
- namedParams: { serverId: '102860784329052160' },
- staticPreview: this.render({ members: 23 }),
- documentation,
+ static openApi = {
+ '/discord/{serverId}': {
+ get: {
+ summary: 'Discord',
+ description,
+ parameters: pathParams({
+ name: 'serverId',
+ example: '102860784329052160',
+ }),
+ },
  },
- ]
+ }
 
  static _cacheLength = 30
 

services/netlify/netlify.service.js

@@ -1,5 +1,5 @@
 import { renderBuildStatusBadge } from '../build-status.js'
-import { BaseSvgScrapingService } from '../index.js'
+import { BaseSvgScrapingService, pathParams } from '../index.js'
 
 const pendingStatus = 'building'
 const notBuiltStatus = 'not built'
@@ -22,17 +22,19 @@ export default class Netlify extends BaseSvgScrapingService {
  pattern: ':projectId',
  }
 
- static examples = [
- {
- title: 'Netlify',
- namedParams: {
- projectId: 'e6d5a4e0-dee1-4261-833e-2f47f509c68f',
+ static openApi = {
+ '/netlify/{projectId}': {
+ get: {
+ summary: 'Netlify',
+ description:
+ 'To locate your project id, visit your project settings, scroll to "Status badges" under "General", and copy the ID between "/api/v1/badges/" and "/deploy-status" in the code sample',
+ parameters: pathParams({
+ name: 'projectId',
+ example: 'e6d5a4e0-dee1-4261-833e-2f47f509c68f',
+ }),
  },
- documentation:
- 'To locate your project id, visit your project settings, scroll to "Status badges" under "General", and copy the ID between "/api/v1/badges/" and "/deploy-status" in the code sample',
- staticPreview: renderBuildStatusBadge({ status: 'passing' }),
  },
- ]
+ }
 
  static defaultBadgeData = {
  label: 'netlify',

services/opencollective/opencollective-by-tier.service.js

@@ -1,9 +1,9 @@
 import Joi from 'joi'
 import { nonNegativeInteger } from '../validators.js'
-import { BaseJsonService } from '../index.js'
+import { BaseJsonService, pathParams } from '../index.js'
 import { metric } from '../text-formatters.js'
 
-const documentation = `<h3>How to get the tierId</h3>
+const description = `<h3>How to get the tierId</h3>
 <p>According to <a target="_blank" href="https://developer.opencollective.com/#/api/collectives?id=get-members-per-tier">open collectives documentation</a>, you can find the tierId by looking at the URL after clicking on a Tier Card on the collective page. (e.g. tierId for https://opencollective.com/shields/order/2988 is 2988)</p>`
 
 // https://developer.opencollective.com/#/api/collectives?id=get-info
@@ -88,15 +88,24 @@ class OpencollectiveBaseJson extends BaseJsonService {
 export default class OpencollectiveByTier extends OpencollectiveBaseJson {
  static route = this.buildRoute('tier', true)
 
- static examples = [
- {
- title: 'Open Collective members by tier',
- namedParams: { collective: 'shields', tierId: '2988' },
- staticPreview: this.render(8, 'monthly backers'),
- keywords: ['opencollective'],
- documentation,
+ static openApi = {
+ '/opencollective/tier/{collective}/{tierId}': {
+ get: {
+ summary: 'Open Collective members by tier',
+ description,
+ parameters: pathParams(
+ {
+ name: 'collective',
+ example: 'shields',
+ },
+ {
+ name: 'tierId',
+ example: '2988',
+ },
+ ),
+ },
  },
- ]
+ }
 
  static defaultBadgeData = {
  label: 'open collective',

services/pub/pub-common.js

@@ -0,0 +1,4 @@
+const baseDescription =
+ '<p><a href="https://pub.dev/">Pub</a> is a package registry for Dart and Flutter.</p>'
+
+export { baseDescription }

services/pub/pub-likes.service.js

@@ -1,33 +1,33 @@
 import Joi from 'joi'
-import { BaseJsonService } from '../index.js'
+import { BaseJsonService, pathParams } from '../index.js'
 import { metric } from '../text-formatters.js'
 import { nonNegativeInteger } from '../validators.js'
+import { baseDescription } from './pub-common.js'
 
-const documentation =
- '<p>A measure of how many developers have liked a package. This provides a raw measure of the overall sentiment of a package from peer developers.</p>'
-
-const keywords = ['dart', 'flutter']
+const description = `${baseDescription}
+ <p>This badge shows a measure of how many developers have liked a package. This provides a raw measure of the overall sentiment of a package from peer developers.</p>`
 
 const schema = Joi.object({
  likeCount: nonNegativeInteger,
 }).required()
 
-const title = 'Pub Likes'
-
 export default class PubLikes extends BaseJsonService {
  static category = 'rating'
 
  static route = { base: 'pub/likes', pattern: ':packageName' }
 
- static examples = [
- {
- title,
- keywords,
- documentation,
- namedParams: { packageName: 'analysis_options' },
- staticPreview: this.render({ likeCount: 1000 }),
+ static openApi = {
+ '/pub/likes/{packageName}': {
+ get: {
+ summary: 'Pub Likes',
+ description,
+ parameters: pathParams({
+ name: 'packageName',
+ example: 'analysis_options',
+ }),
+ },
  },
- ]
+ }
 
  static defaultBadgeData = { label: 'likes' }
 

services/pub/pub-points.service.js

@@ -1,34 +1,34 @@
 import Joi from 'joi'
 import { floorCount } from '../color-formatters.js'
-import { BaseJsonService } from '../index.js'
+import { BaseJsonService, pathParams } from '../index.js'
 import { nonNegativeInteger } from '../validators.js'
+import { baseDescription } from './pub-common.js'
 
-const documentation =
- '<p>A measure of quality. This includes several dimensions of quality such as code style, platform support, and maintainability.</p>'
-
-const keywords = ['dart', 'flutter']
+const description = `${baseDescription}
+ <p>This badge shows a measure of quality. This includes several dimensions of quality such as code style, platform support, and maintainability.</p>`
 
 const schema = Joi.object({
  grantedPoints: nonNegativeInteger,
  maxPoints: nonNegativeInteger,
 }).required()
 
-const title = 'Pub Points'
-
 export default class PubPoints extends BaseJsonService {
  static category = 'rating'
 
  static route = { base: 'pub/points', pattern: ':packageName' }
 
- static examples = [
- {
- title,
- keywords,
- documentation,
- namedParams: { packageName: 'analysis_options' },
- staticPreview: this.render({ grantedPoints: 120, maxPoints: 140 }),
+ static openApi = {
+ '/pub/points/{packageName}': {
+ get: {
+ summary: 'Pub Points',
+ description,
+ parameters: pathParams({
+ name: 'packageName',
+ example: 'analysis_options',
+ }),
+ },
  },
- ]
+ }
 
  static defaultBadgeData = { label: 'points' }
 

services/pub/pub-popularity.service.js

@@ -1,32 +1,32 @@
 import Joi from 'joi'
 import { floorCount } from '../color-formatters.js'
-import { BaseJsonService } from '../index.js'
+import { BaseJsonService, pathParams } from '../index.js'
+import { baseDescription } from './pub-common.js'
 
-const documentation =
- '<p>A measure of how many developers use a package, providing insight into what other developers are using.</p>'
-
-const keywords = ['dart', 'flutter']
+const description = `${baseDescription}
+ <p>This badge shows a measure of how many developers use a package, providing insight into what other developers are using.</p>`
 
 const schema = Joi.object({
  popularityScore: Joi.number().min(0).max(1).required(),
 }).required()
 
-const title = 'Pub Popularity'
-
 export default class PubPopularity extends BaseJsonService {
  static category = 'rating'
 
  static route = { base: 'pub/popularity', pattern: ':packageName' }
 
- static examples = [
- {
- title,
- keywords,
- documentation,
- namedParams: { packageName: 'analysis_options' },
- staticPreview: this.render({ popularityScore: 0.9 }),
+ static openApi = {
+ '/pub/popularity/{packageName}': {
+ get: {
+ summary: 'Pub Popularity',
+ description,
+ parameters: pathParams({
+ name: 'packageName',
+ example: 'analysis_options',
+ }),
+ },
  },
- ]
+ }
 
  static defaultBadgeData = { label: 'popularity' }
 

services/pub/pub-publisher.service.js

@@ -1,5 +1,6 @@
 import Joi from 'joi'
 import { BaseJsonService, pathParams } from '../index.js'
+import { baseDescription } from './pub-common.js'
 
 const schema = Joi.object({
  publisherId: Joi.string().allow(null).required(),
@@ -17,6 +18,7 @@ export class PubPublisher extends BaseJsonService {
  '/pub/publisher/{packageName}': {
  get: {
  summary: 'Pub Publisher',
+ description: baseDescription,
  parameters: pathParams({
  name: 'packageName',
  example: 'path',

services/pub/pub.service.js

@@ -1,6 +1,7 @@
 import Joi from 'joi'
 import { latest, renderVersionBadge } from '../version.js'
-import { BaseJsonService, redirector } from '../index.js'
+import { BaseJsonService, redirector, pathParam, queryParam } from '../index.js'
+import { baseDescription } from './pub-common.js'
 
 const schema = Joi.object({
  versions: Joi.array().items(Joi.string()).required(),
@@ -19,21 +20,25 @@ class PubVersion extends BaseJsonService {
  queryParamSchema,
  }
 
- static examples = [
- {
- title: 'Pub Version',
- namedParams: { packageName: 'box2d' },
- staticPreview: renderVersionBadge({ version: 'v0.4.0' }),
- keywords: ['dart', 'dartlang'],
+ static openApi = {
+ '/pub/v/{packageName}': {
+ get: {
+ summary: 'Pub Version',
+ description: baseDescription,
+ parameters: [
+ pathParam({
+ name: 'packageName',
+ example: 'box2d',
+ }),
+ queryParam({
+ name: 'include_prereleases',
+ schema: { type: 'boolean' },
+ example: null,
+ }),
+ ],
+ },
  },
- {
- title: 'Pub Version (including pre-releases)',
- namedParams: { packageName: 'box2d' },
- queryParams: { include_prereleases: null },
- staticPreview: renderVersionBadge({ version: 'v0.4.0' }),
- keywords: ['dart', 'dartlang'],
- },
- ]
+ }
 
  static defaultBadgeData = { label: 'pub' }