FilesExpand file tree

 master

/

generate-api-docs.js

Copy path

Blame

More file actions

Blame

More file actions

Latest commit

 

History

History

History

143 lines (113 loc) · 3.83 KB

 master

/

generate-api-docs.js

Copy path

Top

File metadata and controls

• Code
• Blame

143 lines (113 loc) · 3.83 KB

Raw

Copy raw file

Download raw file

Open symbols panel

Edit and raw actions

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

31

32

33

34

35

36

37

38

39

40

41

42

43

44

45

46

47

48

49

50

51

52

53

54

55

56

57

58

59

60

61

62

63

64

65

66

67

68

69

70

71

72

73

74

75

76

77

78

79

80

81

82

83

84

85

86

87

88

89

90

91

92

93

94

95

96

97

98

99

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

141

142

143

#!/usr/bin/env node

var writeFileSync = require('fs').writeFileSync

var Path = require('path')

var debug = require('debug')('node-github')

var toCamelCase = require('lodash/camelCase')

var upperFirst = require('lodash/upperFirst')

var ROUTES = require('../lib/routes.json')

var DEFINITIONS = require('../lib/definitions.json')

debug('Generating...')

var sections = {}

var apidocs = ''

function prepareApi (struct, baseType) {

if (!baseType) {

baseType = ''

}

var lastSection

Object.keys(struct).sort().forEach(function (routePart) {

var block = struct[routePart]

if (!block) {

return

}

var messageType = baseType + '/' + routePart

if (block.url && block.params) {

// we ended up at an API definition part!

var parts = messageType.split('/')

var section = toCamelCase(parts[1])

if (!block.method) {

throw new Error('No HTTP method specified for ' + messageType +

'in section ' + section)

}

if (lastSection !== section) {

apidocs += createSectionComment(section)

lastSection = section

}

// add the handler to the sections

if (!sections[section]) {

sections[section] = []

}

parts.splice(0, 2)

var funcName = toCamelCase(parts.join('-'))

apidocs += createComment(section, funcName, block)

} else {

// recurse into this block next:

prepareApi(block, messageType)

}

})

}

function createSectionComment (section) {

return [

'/**',

' * ' + upperFirst(section),

' * @namespace ' + section,

' */',

'',

''

].join('\n')

}

function createComment (section, funcName, block) {

var method = block['method'].toUpperCase()

var url = block['url']

var commentLines = [

'/**',

' * @api {' + method + '} ' + url + ' ' + funcName,

' * @apiName ' + funcName,

' * @apiDescription ' + block['description'],

' * @apiGroup ' + section,

' *'

]

var paramsObj = block['params']

// sort params so Required come before Optional

var paramKeys = Object.keys(paramsObj)

paramKeys.sort(function (paramA, paramB) {

var cleanParamA = paramA.replace(/^\$/, '')

var cleanParamB = paramB.replace(/^\$/, '')

var paramInfoA = paramsObj[paramA] || DEFINITIONS['params'][cleanParamA]

var paramInfoB = paramsObj[paramB] || DEFINITIONS['params'][cleanParamB]

var paramRequiredA = paramInfoA['required']

var paramRequiredB = paramInfoB['required']

if (paramRequiredA && !paramRequiredB) return -1

if (!paramRequiredA && paramRequiredB) return 1

return 0

})

paramKeys.forEach(function (param) {

var cleanParam = param.replace(/^\$/, '')

var paramInfo = paramsObj[param] || DEFINITIONS['params'][cleanParam]

var paramRequired = paramInfo['required']

var paramType = paramInfo['type'].toLowerCase()

var paramDescription = paramInfo['description']

var paramDefaultVal = paramInfo['default']

var paramLabel = cleanParam

// add default value if there is one

if (typeof paramDefaultVal !== 'undefined') {

paramLabel += '=' + paramDefaultVal

}

// show param as either required or optional

if (!paramRequired) {

paramLabel = '[' + paramLabel + ']'

}

var allowedValues = ''

if (paramInfo['enum']) {

allowedValues = '=' + paramInfo['enum'].map(function (val) {

return val // "\"" + val + "\"";

}).join(',')

}

commentLines.push(' * @apiParam {' + paramType + allowedValues + '} ' + paramLabel + ' ' + paramDescription)

})

commentLines.push(' * @apiExample {js} ex:\ngithub.' + section + '.' + funcName + '({ ... })')

return commentLines.join('\n') + '\n */\n\n'

}

debug('Converting routes to functions')

prepareApi(ROUTES)

var apidocsPath = Path.join(__dirname, '..', 'doc', 'apidoc.js')

writeFileSync(apidocsPath, apidocs.trim() + '\n')