Sharing my helper scripts

[dadamssg]

Hey thank you all for this project. It has been really easy to get started with and use. My team has been using it to document our massive api that contains a ton of different fields in the json payloads. I've written some little tools to make some things even easier. I can create a PR to add these to the project or just the docs somewhere or you can just ignore/close this issue.

(editor integration assumes WebStorm usage but i assume you can do the same with other editors)

Formatting JSON

Formatting json inside of comments is a bit of a pain. I wrote a little helper script that can be configured by your editor to use to make that easier. It formats the JSON as well as alphabetically orders the json keys. Add the following to your project:

#!/usr/bin/env node

// ./tools/json-comment.js

const fs = require('fs')
const {sortObj} = require('jsonabc')
const file = process.argv[2]
const lineNo = Number(process.argv[3])
const columnNo = Number(process.argv[4])
const content = fs.readFileSync(file).toString()
const lines = content.split('\n')
const line = lines[lineNo - 1]
const json = sortObj(JSON.parse(line.substr(columnNo - 1)))
const jsonLines = JSON.stringify(json, null, 2).split('\n').map(l => ` *     ${l}`)
lines.splice(lineNo - 1, 0, ...jsonLines)
lines.splice((lineNo + jsonLines.length - 1), 1)
fs.writeFileSync(file, lines.join('\n'))
process.exit(0)

To set it up in WebStorm, open preferences and add a new External Tool with the following filled out:

• Name: json-comment
• Program: node
• Arguments: ./tools/json-comment.js $FilePath$ $LineNumber$ $ColumnNumber$
• Working directory: $ProjectFileDir$
• Advanced Options > Uncheck Open console for tool output

Now after you copy a single line of json from the Chrome dev tools panel you:

• paste it in
• move your cursor to the first character of json
• bring up the WebStorm search bar(double tap shift) and start typing and select json-comment

* This only works on self-contained single line json. Because of WebStorm's auto-save feature sometimes you can attempt to run it and it won't do anything. Save the file, cmd + s or ctr + s, and try again.

(gif was created before i added the ordering of the json feature)

If you come across json that is already formatted that you need to include, you can minify it with this tool. This will give you a single line of json which you can then use json-comment on.

Reformatting already written JSON

json-comment-reformat.js is for reformatting/reordering your existing json comments.

#!/usr/bin/env node

// ./tools/json-comment-reformat.js

const fs = require('fs')
const {sortObj} = require('jsonabc')
const file = process.argv[2]
const startLineNo = Number(process.argv[3])
const endLineNo = Number(process.argv[4])
const content = fs.readFileSync(file).toString()
const lines = content.split('\n')
const commentedJsonLines = lines.splice(startLineNo - 1, (endLineNo - startLineNo) + 1)
const jsonString = commentedJsonLines.map(line => line.replace('*', '').trim()).join('\n')
const json = sortObj(JSON.parse(jsonString))
const jsonLines = JSON.stringify(json, null, 2).split('\n').map(l => ` *     ${l}`)
lines.splice(startLineNo - 1, 0, ...jsonLines)
fs.writeFileSync(file, lines.join('\n'))
process.exit(0)

To set up as a WebStorm External Tool:

• Name: json-comment-reformat
• Program: node
• Arguments: ./tools/json-comment-reformat.js $FilePath$ $SelectionStartLine$ $SelectionEndLine$
• Working directory: $ProjectFileDir$
• Advanced Options > Uncheck Open console for tool output

Use by:

• highlighting the existing json comment
• bring up the WebStorm search bar(double tap shift) and start typing and select json-comment-reformat

Order param tables

Now that the json is looking nice and orderly, i wrote a plugin to alphabetically order the param tables by field name:

// ./tools/orderFieldsFilter.js

/**
 * Alphabetically orders param tables by field name
 */
function postFilter(parsedFiles, filenames, tagName) {
  tagName = tagName || 'parameter'
  parsedFiles.forEach((parsedFile) => {
    parsedFile.forEach((block) => {
      if (block.local[tagName] && block.local[tagName].fields) {
        const blockFields = block.local[tagName].fields
        Object.keys(blockFields).forEach((blockFieldKey) => {
          const fields = block.local[tagName].fields[blockFieldKey]
          block.local[tagName].fields[blockFieldKey] = fields.sort((a, b) => {
            if (a.field > b.field) return 1
            if (a.field < b.field) return -1
            return 0
          })
        })
      }
    })
  })
}

module.exports = {
  postFilter
}

And usage:

apidoc --parse-filters orderFieldsFilter=tools/orderFieldsFilter.js -i src/ -o dist/

This has made our docs easier to read and saved my team a lot of time so I thought I'd share.

[NicolasCARPi]

Hello,

Thanks for sharing this. Maybe it can be included in the wiki.

[dadamssg]

Added json ordering in my filter plugin so now it will do that automatically and will warn us if it encounters invalid json.

//  tools/orderFilter.js

const get = require('lodash/get')
const {sortObj} = require('jsonabc')

/**
 * Alphabetically order params, json request, success, and error examples
 */
function postFilter(parsedFiles, filenames, tagName) {
  tagName = tagName || 'parameter'
  parsedFiles.forEach((parsedFile, fileIndex) => {
    parsedFile.forEach((block) => {
      const filename = filenames[fileIndex]
      orderParamFields(block, tagName)
      orderRequestPayloadExamples(block, filename)
      orderResponseExamples(block, 'success', filename)
      orderResponseExamples(block, 'error', filename)
    })
  })
}

function orderParamFields (block, tagName) {
  if (block.local[tagName] && block.local[tagName].fields) {
    const blockFields = block.local[tagName].fields
    Object.keys(blockFields).forEach((blockFieldKey) => {
      const fields = block.local[tagName].fields[blockFieldKey]
      block.local[tagName].fields[blockFieldKey] = fields.sort((a, b) => {
        if (a.field > b.field) return 1
        if (a.field < b.field) return -1
        return 0
      })
    })
  }
}

function orderRequestPayloadExamples(block, filename) {
  const parameterExamples = get(block, 'local.parameter.examples')
  if (parameterExamples) {
    parameterExamples.forEach(example => {
      if (String(get(example, 'content')).trim().substr(0, 1) === '{') {
        try {
          example.content = JSON.stringify(sortObj(JSON.parse(example.content)), null, 2)
        } catch (e) {
          const name = get(block, 'local.name')
          console.error(`Invalid json request example: ${name || filename}`)
          if (!name) {
            console.error(example.content)
          }
        }
      }
    })
  }
}

function orderResponseExamples(block, type, filename) {
  const examples = get(block, `local.${type}.examples`)
  if (!Array.isArray(examples)) return
  examples.forEach(example => {
    const name = get(block, 'local.name', '')
    const content = String(get(example, 'content'))
    // some responses have the status(ex: HTTP/1.1 200 OK) on the first line
    const firstOpenBracketPos = content.indexOf('{')
    if (firstOpenBracketPos > -1) {
      const json = content
        .substr(firstOpenBracketPos)
        .split('\n')
        .map(l => l.trim())
        .join('')
      try {
        const status = content.substr(0, firstOpenBracketPos).trim()
        example.content = status + (status ? '\n' : '') +  JSON.stringify(sortObj(JSON.parse(json)), null, 2)
      } catch (e) {
        const globalName = get(block, 'global.define.name', '')
        const info = [`Invalid json ${type} example:`, globalName, name, filename, `- ${e.message}`].filter(Boolean)
        console.log(...info)
      }
    }
  })
}

module.exports = {
  postFilter
}

[NicolasCARPi]

I think at this point the best course of action is for you to create a repository and the scripts and a README and I'll just point to that repo in the doc.

[dadamssg]

Sure thing, i'll just put it all in a package.

[dadamssg]

eh, on second thought i'll just create a gist with the code. My code makes the assumption that there is a single space before the starting * which is a big assumption for a package to make.

[NicolasCARPi]

It doesn't have to be a full fledged package, but a repo will allow to regroup the different scripts and add a README and a licence, whereas a gist seems a bit light.