Source: core/base-service/openapi.js

  1. /**
  2.  * Functions for publishing the shields.io URL schema as an OpenAPI Document
  3.  *
  4.  * @module
  5.  */
  7. const baseUrl = process.env.BASE_URL
  8. const globalParamRefs = [
  9.   { $ref: '#/components/parameters/style' },
  10.   { $ref: '#/components/parameters/logo' },
  11.   { $ref: '#/components/parameters/logoColor' },
  12.   { $ref: '#/components/parameters/logoSize' },
  13.   { $ref: '#/components/parameters/label' },
  14.   { $ref: '#/components/parameters/labelColor' },
  15.   { $ref: '#/components/parameters/color' },
  16.   { $ref: '#/components/parameters/cacheSeconds' },
  17.   { $ref: '#/components/parameters/link' },
  18. ]
  20. function getCodeSamples(altText) {
  21.   return [
  22.     {
  23.       lang: 'URL',
  24.       label: 'URL',
  25.       source: '$url',
  26.     },
  27.     {
  28.       lang: 'Markdown',
  29.       label: 'Markdown',
  30.       source: `![${altText}]($url)`,
  31.     },
  32.     {
  33.       lang: 'reStructuredText',
  34.       label: 'rSt',
  35.       source: `.. image:: $url\n   :alt: ${altText}`,
  36.     },
  37.     {
  38.       lang: 'AsciiDoc',
  39.       label: 'AsciiDoc',
  40.       source: `image:$url[${altText}]`,
  41.     },
  42.     {
  43.       lang: 'HTML',
  44.       label: 'HTML',
  45.       source: `<img alt="${altText}" src="$url">`,
  46.     },
  47.   ]
  48. }
  50. function getEnum(pattern, paramName) {
  51.   const re = new RegExp(`${paramName}\\(([A-Za-z0-9_\\-|]+)\\)`)
  52.   const match = pattern.match(re)
  53.   if (match === null) {
  54.     return undefined
  55.   }
  56.   if (!match[1].includes('|')) {
  57.     return undefined
  58.   }
  59.   return match[1].split('|')
  60. }
  62. function addGlobalProperties(endpoints) {
  63.   const paths = {}
  64.   for (const key of Object.keys(endpoints)) {
  65.     paths[key] = endpoints[key]
  66.     paths[key].get.parameters = [
  67.       ...paths[key].get.parameters,
  68.       ...globalParamRefs,
  69.     ]
  70.     paths[key].get['x-code-samples'] = getCodeSamples(paths[key].get.summary)
  71.   }
  72.   return paths
  73. }
  75. function sortPaths(obj) {
  76.   const entries = Object.entries(obj)
  77.   entries.sort((a, b) => a[1].get.summary.localeCompare(b[1].get.summary))
  78.   return Object.fromEntries(entries)
  79. }
  81. function services2openapi(services, sort) {
  82.   const paths = {}
  83.   for (const service of services) {
  84.     for (const [key, value] of Object.entries(
  85.       addGlobalProperties(service.openApi),
  86.     )) {
  87.       if (key in paths) {
  88.         throw new Error(`Conflicting route: ${key}`)
  89.       }
  90.       paths[key] = value
  91.     }
  92.   }
  93.   return sort ? sortPaths(paths) : paths
  94. }
  96. function category2openapi({ category, services, sort = false }) {
  97.   const spec = {
  98.     openapi: '3.0.0',
  99.     info: {
  100.       version: '1.0.0',
  101.       title: category.name,
  102.       license: {
  103.         name: 'CC0',
  104.       },
  105.     },
  106.     servers: baseUrl ? [{ url: baseUrl }] : undefined,
  107.     components: {
  108.       parameters: {
  109.         style: {
  110.           name: 'style',
  111.           in: 'query',
  112.           required: false,
  113.           description: `If not specified, the default style for this badge is "${
  114.             category.name.toLowerCase() === 'social' ? 'social' : 'flat'
  115.           }".`,
  116.           schema: {
  117.             type: 'string',
  118.             enum: ['flat', 'flat-square', 'plastic', 'for-the-badge', 'social'],
  119.           },
  120.           example: 'flat',
  121.         },
  122.         logo: {
  123.           name: 'logo',
  124.           in: 'query',
  125.           required: false,
  126.           description:
  127.             'Icon slug from simple-icons. You can click the icon title on <a href="https://simpleicons.org/" rel="noopener noreferrer" target="_blank">simple-icons</a> to copy the slug or they can be found in the <a href="https://github.com/simple-icons/simple-icons/blob/master/slugs.md">slugs.md file</a> in the simple-icons repository. <a href="/docs/logos">Further info</a>.',
  128.           schema: {
  129.             type: 'string',
  130.           },
  131.           example: 'appveyor',
  132.         },
  133.         logoColor: {
  134.           name: 'logoColor',
  135.           in: 'query',
  136.           required: false,
  137.           description:
  138.             'The color of the logo (hex, rgb, rgba, hsl, hsla and css named colors supported). Supported for simple-icons logos but not for custom logos.',
  139.           schema: {
  140.             type: 'string',
  141.           },
  142.           example: 'violet',
  143.         },
  144.         logoSize: {
  145.           name: 'logoSize',
  146.           in: 'query',
  147.           required: false,
  148.           description:
  149.             'Make icons adaptively resize by setting `auto`. Useful for some wider logos like `amd` and `amg`. Supported for simple-icons logos but not for custom logos.',
  150.           schema: {
  151.             type: 'string',
  152.           },
  153.           example: 'auto',
  154.         },
  155.         label: {
  156.           name: 'label',
  157.           in: 'query',
  158.           required: false,
  159.           description:
  160.             'Override the default left-hand-side text (<a href="https://developer.mozilla.org/en-US/docs/Glossary/percent-encoding">URL-Encoding</a> needed for spaces or special characters!)',
  161.           schema: {
  162.             type: 'string',
  163.           },
  164.           example: 'healthiness',
  165.         },
  166.         labelColor: {
  167.           name: 'labelColor',
  168.           in: 'query',
  169.           required: false,
  170.           description:
  171.             'Background color of the left part (hex, rgb, rgba, hsl, hsla and css named colors supported).',
  172.           schema: {
  173.             type: 'string',
  174.           },
  175.           example: 'abcdef',
  176.         },
  177.         color: {
  178.           name: 'color',
  179.           in: 'query',
  180.           required: false,
  181.           description:
  182.             'Background color of the right part (hex, rgb, rgba, hsl, hsla and css named colors supported).',
  183.           schema: {
  184.             type: 'string',
  185.           },
  186.           example: 'fedcba',
  187.         },
  188.         cacheSeconds: {
  189.           name: 'cacheSeconds',
  190.           in: 'query',
  191.           required: false,
  192.           description:
  193.             'HTTP cache lifetime (rules are applied to infer a default value on a per-badge basis, any values specified below the default will be ignored).',
  194.           schema: {
  195.             type: 'string',
  196.           },
  197.           example: '3600',
  198.         },
  199.         link: {
  200.           name: 'link',
  201.           in: 'query',
  202.           required: false,
  203.           description:
  204.             'Specify what clicking on the left/right of a badge should do. Note that this only works when integrating your badge in an `<object>` HTML tag, but not an `<img>` tag or a markup language.',
  205.           style: 'form',
  206.           explode: true,
  207.           schema: {
  208.             type: 'array',
  209.             maxItems: 2,
  210.             items: {
  211.               type: 'string',
  212.             },
  213.           },
  214.         },
  215.       },
  216.     },
  217.     paths: services2openapi(services, sort),
  218.   }
  220.   return spec
  221. }
  223. /**
  224.  * Helper function for assembling an OpenAPI path parameter object
  225.  *
  226.  * @param {module:core/base-service/openapi~PathParamInput} param Input param
  227.  * @returns {module:core/base-service/openapi~OpenApiParam} OpenAPI Parameter Object
  228.  * @see https://swagger.io/specification/#parameter-object
  229.  */
  230. function pathParam({
  231.   name,
  232.   example,
  233.   schema = { type: 'string' },
  234.   description,
  235. }) {
  236.   return { name, in: 'path', required: true, schema, example, description }
  237. }
  239. /**
  240.  * Helper function for assembling an array of OpenAPI path parameter objects
  241.  * The code
  242.  * ```
  243.  * const params = pathParams(
  244.  *   { name: 'name1', example: 'example1' },
  245.  *   { name: 'name2', example: 'example2' },
  246.  * )
  247.  * ```
  248.  * is equivalent to
  249.  * ```
  250.  * const params = [
  251.  *   pathParam({ name: 'name1', example: 'example1' }),
  252.  *   pathParam({ name: 'name2', example: 'example2' }),
  253.  * ]
  254.  * ```
  255.  *
  256.  * @param {...module:core/base-service/openapi~PathParamInput} params Input params
  257.  * @returns {Array.<module:core/base-service/openapi~OpenApiParam>} Array of OpenAPI Parameter Objects
  258.  * @see {@link module:core/base-service/openapi~pathParam}
  259.  */
  260. function pathParams(...params) {
  261.   return params.map(param => pathParam(param))
  262. }
  264. /**
  265.  * Helper function for assembling an OpenAPI query parameter object
  266.  *
  267.  * @param {module:core/base-service/openapi~QueryParamInput} param Input param
  268.  * @returns {module:core/base-service/openapi~OpenApiParam} OpenAPI Parameter Object
  269.  * @see https://swagger.io/specification/#parameter-object
  270.  */
  271. function queryParam({
  272.   name,
  273.   example,
  274.   schema = { type: 'string' },
  275.   required = false,
  276.   description,
  277. }) {
  278.   const param = { name, in: 'query', required, schema, example, description }
  279.   if (example === null && schema.type === 'boolean') {
  280.     param.allowEmptyValue = true
  281.   }
  282.   return param
  283. }
  285. /**
  286.  * Helper function for assembling an array of OpenAPI query parameter objects
  287.  * The code
  288.  * ```
  289.  * const params = queryParams(
  290.  *   { name: 'name1', example: 'example1' },
  291.  *   { name: 'name2', example: 'example2' },
  292.  * )
  293.  * ```
  294.  * is equivalent to
  295.  * ```
  296.  * const params = [
  297.  *   queryParam({ name: 'name1', example: 'example1' }),
  298.  *   queryParam({ name: 'name2', example: 'example2' }),
  299.  * ]
  300.  * ```
  301.  *
  302.  * @param {...module:core/base-service/openapi~QueryParamInput} params Input params
  303.  * @returns {Array.<module:core/base-service/openapi~OpenApiParam>} Array of OpenAPI Parameter Objects
  304.  * @see {@link module:core/base-service/openapi~queryParam}
  305.  */
  306. function queryParams(...params) {
  307.   return params.map(param => queryParam(param))
  308. }
  310. /**
  311.  * @typedef {object} PathParamInput
  312.  * @property {string} name The name of the parameter. Parameter names are case sensitive
  313.  * @property {string} example Example of a valid value for this parameter
  314.  * @property {object} [schema={ type: 'string' }] Parameter schema.
  315.  *    An [OpenAPI Schema object](https://swagger.io/specification/#schema-object)
  316.  *    specifying the parameter type.
  317.  *    Normally this should be omitted as all path parameters are strings.
  318.  *    Use this when we also want to pass an enum of valid parameters
  319.  *    to be presented as a drop-down in the frontend. e.g:
  320.  *    `{'type': 'string', 'enum': ['github', 'bitbucket'}` (Optional)
  321.  * @property {string} description A brief description of the parameter (Optional)
  322.  */
  324. /**
  325.  * @typedef {object} QueryParamInput
  326.  * @property {string} name The name of the parameter. Parameter names are case sensitive
  327.  * @property {string|null} example Example of a valid value for this parameter
  328.  * @property {object} [schema={ type: 'string' }] Parameter schema.
  329.  *    An [OpenAPI Schema object](https://swagger.io/specification/#schema-object)
  330.  *    specifying the parameter type. This can normally be omitted.
  331.  *    Query params are usually strings. (Optional)
  332.  * @property {boolean} [required=false] Determines whether this parameter is mandatory (Optional)
  333.  * @property {string} description A brief description of the parameter (Optional)
  334.  */
  336. /**
  337.  * OpenAPI Parameter Object
  338.  *
  339.  * @typedef {object} OpenApiParam
  340.  * @property {string} name The name of the parameter
  341.  * @property {string|null} example Example of a valid value for this parameter
  342.  * @property {('path'|'query')} in The location of the parameter
  343.  * @property {object} schema Parameter schema.
  344.  *    An [OpenAPI Schema object](https://swagger.io/specification/#schema-object)
  345.  *    specifying the parameter type.
  346.  * @property {boolean} required Determines whether this parameter is mandatory
  347.  * @property {string} description A brief description of the parameter
  348.  * @property {boolean} allowEmptyValue If true, allows the ability to pass an empty value to this parameter
  349.  */
  351. export {
  352.   category2openapi,
  353.   getEnum,
  354.   pathParam,
  355.   pathParams,
  356.   queryParam,
  357.   queryParams,
  358. }