WIP refactor: generate openapi directly instead of legacy format

lib/endpoint/add-code-samples.js

@@ -0,0 +1,58 @@
+module.exports = addCodeSamples
+
+const urlTemplate = require('url-template')
+const { stringify } = require('javascript-stringify')
+
+// TODO: find a better place to define parameter examples
+const PARAMETER_EXAMPLES = {
+  owner: 'octocat',
+  repo: 'hello-world',
+  issue_number: 1,
+  title: 'title'
+}
+
+function addCodeSamples (state) {
+  const { scope, baseUrl } = state
+
+  state.routes.forEach(route => {
+    const codeSampleParams = { route, scope, baseUrl }
+    route.operation['x-code-samples'] = route.operation['x-code-samples'].concat(
+      { lang: 'Shell', source: toShellExample(codeSampleParams) },
+      { lang: 'JS', source: toJsExample(codeSampleParams) }
+    )
+  })
+}
+
+function toShellExample ({ route, scope, baseUrl }) {
+  const path = urlTemplate.parse(route.path.replace(/:(\w+)/, '{$1}')).expand(PARAMETER_EXAMPLES)
+  const params = route.operation.parameters
+    .filter(param => !param.deprecated)
+    .filter(param => param.location === 'body')
+    .filter(param => param.required)
+    .reduce((params, param) => Object.assign(params, {
+      [param.name]: PARAMETER_EXAMPLES[param.name] || param.name
+    }), {})
+
+  const method = route.method.toUpperCase()
+  const defaultAcceptHeader = route.operation.parameters[0].schema.default
+
+  const args = [
+    method !== 'GET' && `-X${method}`,
+    `-H"Accept: ${defaultAcceptHeader}"`,
+    new URL(path, baseUrl).href,
+    Object.keys(params).length && `-d '${JSON.stringify(params)}'`
+  ].filter(Boolean)
+  return `curl \\\n  ${args.join(' \\\n  ')}`
+}
+
+function toJsExample ({ route, scope, baseUrl }) {
+  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]: PARAMETER_EXAMPLES[param.name] || param.name
+    }), {})
+
+  return `octokit.${scope}.get(${Object.keys(params).length ? stringify(params, null, 2) : ''})`
+}

lib/endpoint/add-triggers-notification-flag.js

@@ -9,9 +9,9 @@ module.exports = addTriggersNotificationFlag
  * - Source: https://developer.github.com/v3/guides/best-practices-for-integrators/#dealing-with-abuse-rate-limits
  */
 function addTriggersNotificationFlag (state) {
-  state.results.forEach(endpoint => {
-    if (/This endpoint triggers \[notifications\]/.test(endpoint.description)) {
-      endpoint.triggersNotification = true
+  state.routes.forEach(route => {
+    if (/This endpoint triggers \[notifications\]/.test(route.operation.description)) {
+      route.operation['x-github'].triggersNotification = true
     }
   })
 }

lib/endpoint/find-accept-header.js

@@ -0,0 +1,28 @@
+module.exports = findAcceptHeader
+
+function findAcceptHeader (state) {
+  const previewBlocks = state.blocks.filter(block => block.type === 'preview')
+
+  state.routes.forEach(route => {
+    // TODO: handle optional preview blocks
+    const requiredPreviewHeaderBlocks = previewBlocks.filter(block => block.required)
+    const defaultAcceptHeader = requiredPreviewHeaderBlocks.length
+      ? requiredPreviewHeaderBlocks.map(block => `application/vnd.github.${block.preview}-preview+json`).join(',')
+      : 'application/vnd.github.v3+json'
+    const acceptHeaderParam = {
+      name: 'accept',
+      description: requiredPreviewHeaderBlocks.length ? 'This API is under preview and subject to change.' : 'Setting to `application/vnd.github.v3+json` is recommended',
+      in: 'header',
+      schema: {
+        type: 'string',
+        default: defaultAcceptHeader
+      }
+    }
+
+    if (requiredPreviewHeaderBlocks.length) {
+      acceptHeaderParam.required = true
+    }
+
+    route.operation.parameters.unshift(acceptHeaderParam)
+  })
+}

lib/endpoint/find-deprecation-notices.js

@@ -12,10 +12,10 @@ function findDeprecationNotices (state) {
     .filter(block => block.type === 'DeprecationTitle')
     .map(getDeprecationContext)
 
-  state.results.forEach(result => {
+  state.routes.forEach(route => {
     deprecationBlocks.forEach(deprecationBlock => {
       if (deprecationBlock.context === CONTEXT_ROUTE) {
-        result.isDeprecated = true
+        route.operation.deprecated = true
       }
       // TODO: handle deprecation notices that are not for the route, e.g.:
       //       The rate object is deprecated in the /rate_limit response

lib/endpoint/find-description.js

@@ -9,7 +9,7 @@ function findDescription (state) {
     .join('\n\n')
 
   const newDescription = normalizeMarkdown(state, description)
-  state.results.forEach(result => {
-    result.description = newDescription
+  state.routes.forEach(route => {
+    route.operation.description = newDescription
   })
 }

lib/endpoint/find-is-github-cloud.js

@@ -7,8 +7,8 @@ function findIsGitHubCloud (state) {
 
   const githubCloudOnly = isGitHubCloud(state)
 
-  state.results.forEach(result => {
-    result.githubCloudOnly = githubCloudOnly
+  state.routes.forEach(route => {
+    route.operation['x-github'].githubCloudOnly = githubCloudOnly
   })
 }