elasticsearch-js/scripts/utils/generateDocs.js

/*
 * Licensed to Elasticsearch B.V. under one or more contributor
 * license agreements. See the NOTICE file distributed with
 * this work for additional information regarding copyright
 * ownership. Elasticsearch B.V. licenses this file to you under
 * the Apache License, Version 2.0 (the "License"); you may
 * not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *    http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 */

'use strict'

const dedent = require('dedent')

function generateDocs (common, spec) {
  var doc = '= API Reference\n\n'
  doc += commonParameters(common)
  spec.forEach(s => {
    doc += '\n' + generateApiDoc(s)
  })
  return doc
}

function commonParameters (spec) {
  var doc = dedent`
  === Common parameters
  Parameters that are accepted by all API endpoints.
  https://www.elastic.co/guide/en/elasticsearch/reference/current/common-options.html
  [cols=2*]
  |===\n`
  Object.keys(spec.params).forEach(key => {
    const name = isSnakeCased(key) && key !== camelify(key)
      ? '`' + key + '` or `' + camelify(key) + '`'
      : '`' + key + '`'

    doc += dedent`
    |${name}
    |${'`' + spec.params[key].type + '`'} - ${spec.params[key].description}`
    if (spec.params[key].default) {
      doc += ` +
    _Default:_ ${'`' + spec.params[key].default + '`'}`
    }
    doc += '\n\n'
  })

  doc += dedent`
  |===
  `
  return doc
}

function generateApiDoc (spec) {
  const name = Object.keys(spec)[0]
  const documentationUrl = spec[name].documentation
  const params = []
  // url params
  const urlParts = spec[name].url.parts
  if (urlParts) {
    Object.keys(urlParts).forEach(param => {
      params.push({
        name: param,
        type: getType(urlParts[param].type, urlParts[param].options),
        description: urlParts[param].description,
        default: urlParts[param].default
      })
    })
  }

  // query params
  const urlParams = spec[name].url.params
  if (urlParams) {
    Object.keys(urlParams).forEach(param => {
      params.push({
        name: param,
        type: getType(urlParams[param].type, urlParams[param].options),
        description: urlParams[param].description,
        default: urlParams[param].default
      })
    })
  }

  // body params
  const body = spec[name].body
  if (body) {
    params.push({
      name: 'body',
      type: 'object',
      description: body.description,
      default: body.default
    })
  }

  var doc = dedent`
  === ${camelify(name)}
  [source,js]
  ----
  client.${camelify(name)}([params] [, options] [, callback])
  ----
  ${documentationUrl || ''}
  [cols=2*]
  |===`

  doc += '\n' + params.reduce((acc, val) => {
    const name = isSnakeCased(val.name) && val.name !== camelify(val.name)
      ? '`' + val.name + '` or `' + camelify(val.name) + '`'
      : '`' + val.name + '`'
    acc += dedent`
    |${name}
    |${'`' + val.type + '`'} - ${val.description}`
    if (val.default) {
      acc += ` +
    _Default:_ ${'`' + val.default + '`'}`
    }
    return acc + '\n\n'
  }, '')

  doc += dedent`
  |===
  `
  return doc
}

function getType (type, options) {
  switch (type) {
    case 'list':
      return 'string, string[]'
    case 'date':
    case 'time':
    case 'timeout':
      return 'string'
    case 'enum':
      return options.map(k => `'${k}'`).join(', ')
    case 'int':
    case 'double':
    case 'long':
      return 'number'
    default:
      return type
  }
}

function camelify (str) {
  return str[0] === '_'
    ? '_' + str.slice(1).replace(/_([a-z])/g, k => k[1].toUpperCase())
    : str.replace(/_([a-z])/g, k => k[1].toUpperCase())
}

function isSnakeCased (str) {
  return !!~str.indexOf('_')
}

module.exports = generateDocs