create-code-samples.js

module.exports = createCodeSamples

const { URL } = require('url')
const urlTemplate = require('url-template')
const { stringify } = require('javascript-stringify')
const { get, mapValues, snakeCase } = require('lodash')

const PARAMETER_EXAMPLES = {
  owner: 'octocat',
  repo: 'hello-world',
  email: 'octocat@github.com',
  emails: ['octocat@github.com']
}

function createCodeSamples (operation) {
  const route = {
    method: operation.verb.toUpperCase(),
    path: operation.requestPath,
    operation
  }
  const serverUrl = operation.serverUrl

  const codeSampleParams = { route, serverUrl }
  return [
    { lang: 'Shell', source: toShellExample(codeSampleParams) },
    { lang: 'JavaScript', source: toJsExample(codeSampleParams) }
  ]
}

function toShellExample ({ route, serverUrl }) {
  const pathParams = mapValues(getExamplePathParams(route), (value, paramName) =>
    PARAMETER_EXAMPLES[paramName] ? value : snakeCase(value).toUpperCase()
  )
  const path = urlTemplate.parse(route.path.replace(/:(\w+)/g, '{$1}')).expand(pathParams)
  const params = getExampleBodyParams(route)
  const { method } = route

  const requiredPreview = get(route, 'operation.x-github.previews', [])
    .find(preview => preview.required)

  const defaultAcceptHeader = requiredPreview
    ? `application/vnd.github.${requiredPreview.name}-preview+json`
    : 'application/vnd.github.v3+json'

  const args = [
    method !== 'GET' && `-X ${method}`,
    defaultAcceptHeader ? `-H "Accept: ${defaultAcceptHeader}"` : '',
    new URL(path, serverUrl).href,
    Object.keys(params).length && `-d '${JSON.stringify(params)}'`
  ].filter(Boolean)
  return `curl \\\n  ${args.join(' \\\n  ')}`
}

function toJsExample ({ route }) {
  const params = route.operation.parameters
    .filter(param => !param.deprecated)
    .filter(param => param.in !== 'header')
    .filter(param => param.required)
    .reduce(
      (_params, param) =>
        Object.assign(_params, {
          [param.name]: getExampleParamValue(param.name, param.schema)
        }),
      {}
    )
  Object.assign(params, getExampleBodyParams(route))

  // add any required preview headers to the params object
  const requiredPreviewNames = get(route.operation, 'x-github.previews', [])
    .filter(preview => preview.required)
    .map(preview => preview.name)

  if (requiredPreviewNames.length) {
    Object.assign(params, {
      mediaType: { previews: requiredPreviewNames }
    })
  }

  // add required content type header (presently only for `POST /markdown/raw`)
  const contentTypeHeader = route.operation.parameters.find(param => {
    return param.name.toLowerCase() === 'content-type' && get(param, 'schema.enum')
  })

  if (contentTypeHeader) {
    Object.assign(params, {
      headers: { 'content-type': contentTypeHeader.schema.enum[0] }
    })
  }

  const args = Object.keys(params).length ? ', ' + stringify(params, null, 2) : ''
  return `await octokit.request('${route.method} ${route.path}'${args})`
}

function getExamplePathParams ({ operation }) {
  const pathParams = operation.parameters.filter(param => param.in === 'path')
  if (pathParams.length === 0) {
    return {}
  }
  return pathParams.reduce((dict, param) => {
    dict[param.name] = getExampleParamValue(param.name, param.schema)
    return dict
  }, {})
}

function getExampleBodyParams ({ operation }) {
  let schema
  try {
    schema = operation.requestBody.content['application/json'].schema
  } catch (noRequestBody) {
    return {}
  }
  if (operation['x-github'].requestBodyParameterName) {
    const paramName = operation['x-github'].requestBodyParameterName
    return { [paramName]: getExampleParamValue(paramName, schema) }
  }

  if (schema.oneOf) {
    schema = schema.oneOf[0]
  }
  const props =
    schema.required && schema.required.length > 0
      ? schema.required
      : Object.keys(schema.properties).slice(0, 1)
  return props.reduce((dict, propName) => {
    const propSchema = schema.properties[propName]
    if (!propSchema.deprecated) {
      dict[propName] = getExampleParamValue(propName, propSchema)
    }
    return dict
  }, {})
}

function getExampleParamValue (name, schema) {
  const value = PARAMETER_EXAMPLES[name]
  if (value) {
    return value
  }

  // TODO: figure out the right behavior here
  if (schema.oneOf) return getExampleParamValue(name, schema.oneOf[0])
  if (schema.anyOf) return getExampleParamValue(name, schema.anyOf[0])

  switch (schema.type) {
    case 'string':
      return name
    case 'boolean':
      return true
    case 'integer':
      return 42
    case 'object':
      return mapValues(schema.properties, (propSchema, propName) =>
        getExampleParamValue(propName, propSchema)
      )
    case 'array':
      return [getExampleParamValue(name, schema.items)]
  }
  throw new Error(`Unknown data type in schema:, ${JSON.stringify(schema, null, 2)}`)
}