github-docs/script/rest/utils/operation.js at main · 0xdevalias/github-docs · GitHub

History

259 lines (208 loc) · 8.77 KB

Raw

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

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

162

163

164

165

166

167

168

169

170

171

172

173

174

175

176

177

178

179

180

181

182

183

184

185

186

187

188

189

190

191

192

193

194

195

196

197

198

199

200

201

202

203

204

205

206

207

208

209

210

211

212

213

214

215

216

217

218

219

220

221

222

223

224

225

226

227

228

229

230

231

232

233

234

235

236

237

238

239

240

241

242

243

244

245

246

247

248

249

250

251

252

253

254

255

256

257

258

259

const { get, flatten, isPlainObject } = require('lodash')

const { sentenceCase } = require('change-case')

const slugger = new (require('github-slugger'))()

const httpStatusCodes = require('http-status-code')

const renderContent = require('../../../lib/render-content')

const createCodeSamples = require('./create-code-samples')

const Ajv = require('ajv')

// titles that can't be derived by sentence-casing the ID

const categoryTitles = { scim: 'SCIM' }

module.exports = class Operation {

constructor (verb, requestPath, props, serverUrl) {

const defaultProps = {

parameters: [],

'x-codeSamples': [],

responses: {}

}

Object.assign(this, { verb, requestPath, serverUrl }, defaultProps, props)

slugger.reset()

this.slug = slugger.slug(this.summary)

// Add category

// workaround for misnamed `code-scanning.` category bug

// https://github.com/github/rest-api-description/issues/38

this['x-github'].category = this['x-github'].category.replace('.', '')

this.category = this['x-github'].category

this.categoryLabel = categoryTitles[this.category] || sentenceCase(this.category)

// Add subcategory

if (this['x-github'].subcategory) {

this.subcategory = this['x-github'].subcategory

this.subcategoryLabel = sentenceCase(this.subcategory)

}

return this

}

get schema () {

return require('./operation-schema')

}

async process () {

this['x-codeSamples'] = createCodeSamples(this)

await Promise.all([

this.renderDescription(),

this.renderCodeSamples(),

this.renderResponses(),

this.renderParameterDescriptions(),

this.renderBodyParameterDescriptions(),

this.renderPreviewNotes(),

this.renderNotes()

])

const ajv = new Ajv()

const valid = ajv.validate(this.schema, this)

if (!valid) {

console.error(JSON.stringify(ajv.errors, null, 2))

throw new Error('Invalid operation found')

}

async renderDescription () {

this.descriptionHTML = await renderContent(this.description)

return this

}

async renderCodeSamples () {

return Promise.all(this['x-codeSamples'].map(async (sample) => {

const markdown = createCodeBlock(sample.source, sample.lang.toLowerCase())

sample.html = await renderContent(markdown)

return sample

}))

}

async renderResponses () {

// clone and delete this.responses so we can turn it into a clean array of objects

const rawResponses = JSON.parse(JSON.stringify(this.responses))

delete this.responses

this.responses = await Promise.all(Object.keys(rawResponses).map(async (responseCode) => {

const rawResponse = rawResponses[responseCode]

const httpStatusCode = responseCode

const httpStatusMessage = httpStatusCodes.getMessage(Number(responseCode))

const cleanResponses = []

// responses can have zero, one, or multiple examples

const rawExample = get(rawResponse, 'content.application/json.example')

const rawExamples = get(rawResponse, 'content.application/json.examples')

// first handle responses with multiple examples

if (rawExamples) {

for (const rawExampleKey of Object.keys(rawExamples)) {

const rawExample = rawExamples[rawExampleKey]

const cleanResponse = {}

cleanResponse.httpStatusCode = httpStatusCode

cleanResponse.httpStatusMessage = httpStatusMessage

// a handful of examples don't have summary properties with a description,

// so we can sentence case the property name as a fallback

cleanResponse.description = rawExample.summary || sentenceCase(rawExampleKey)

const payloadMarkdown = createCodeBlock(rawExample.value, 'json')

cleanResponse.payload = await renderContent(payloadMarkdown)

cleanResponses.push(cleanResponse)

}

} else { // then handle responses with either one or zero examples

const cleanResponse = {}

cleanResponse.httpStatusCode = responseCode

cleanResponse.httpStatusMessage = httpStatusCodes.getMessage(Number(responseCode))

cleanResponse.description = sentenceCase(rawResponse.description)

if (rawExample) {

const payloadMarkdown = createCodeBlock(rawExample, 'json')

cleanResponse.payload = await renderContent(payloadMarkdown)

}

cleanResponses.push(cleanResponse)

}

// tidy up descriptions

return cleanResponses.map(response => {

response.description = response.description

.replace('Example of', 'Response for')

.replace('Empty response', 'Default Response')

.replace(/^Default$/, 'Default response')

return response

})

}))

// flatten child arrays

this.responses = flatten(this.responses)

}

async renderParameterDescriptions () {

return Promise.all(this.parameters.map(async (param) => {

param.descriptionHTML = await renderContent(param.description)

return param

}))

}

async renderBodyParameterDescriptions () {

const bodyParamsObject = get(this, 'requestBody.content.application/json.schema.properties', {})

const requiredParams = get(this, 'requestBody.content.application/json.schema.required', [])

this.bodyParameters = await getBodyParams(bodyParamsObject, requiredParams)

}

async renderPreviewNotes () {

const previews = get(this, 'x-github.previews', [])

.filter(preview => preview.note)

return Promise.all(previews.map(async (preview) => {

const note = preview.note

// remove extra leading and trailing newlines

.replace(/```\n\n\n/mg, '```\n')

.replace(/```\n\n/mg, '```\n')

.replace(/\n\n\n```/mg, '\n```')

.replace(/\n\n```/mg, '\n```')

// convert single-backtick code snippets to fully fenced triple-backtick blocks

// example: This is the description.\n\n`application/vnd.github.machine-man-preview+json`

.replace(/\n`application/, '\n```\napplication')

.replace(/json`$/, 'json\n```')

preview.html = await renderContent(note)

}))

}

// add additional notes to this array whenever we want

async renderNotes () {

this.notes = []

return Promise.all(this.notes.map(async (note) => renderContent(note)))

}

// need to use this function recursively to get child and grandchild params

async function getBodyParams (paramsObject, requiredParams) {

if (!isPlainObject(paramsObject)) return []

return Promise.all(Object.keys(paramsObject).map(async (paramKey) => {

const param = paramsObject[paramKey]

param.name = paramKey

param.in = 'body'

param.rawType = param.type

param.rawDescription = param.description

// e.g. array of strings

param.type = param.type === 'array'

? `array of ${param.items.type}s`

: param.type

// e.g. object or null

param.type = param.nullable

? `${param.type} or null`

: param.type

const isRequired = requiredParams && requiredParams.includes(param.name)

const requiredString = isRequired ? '**Required**. ' : ''

param.description = await renderContent(requiredString + param.description)

// there may be zero, one, or multiple object parameters that have children parameters

param.childParamsGroups = []

const childParamsGroup = await getChildParamsGroup(param)

if (childParamsGroup && childParamsGroup.params.length) {

param.childParamsGroups.push(childParamsGroup)

}

// if the param is an object, it may have child object params that have child params :/

if (param.rawType === 'object') {

param.childParamsGroups.push(...flatten(childParamsGroup.params

.filter(param => param.childParamsGroups.length)

.map(param => param.childParamsGroups)))

}

return param

}))

}

async function getChildParamsGroup (param) {

// only objects and arrays of objects ever have child params

if (!(param.rawType === 'array' || param.rawType === 'object')) return

if (param.items && param.items.type !== 'object') return

const childParamsObject = param.rawType === 'array' ? param.items.properties : param.properties

const requiredParams = param.rawType === 'array' ? param.items.required : param.required

const childParams = await getBodyParams(childParamsObject, requiredParams)

// adjust the type for easier readability in the child table

const parentType = param.rawType === 'array' ? 'items' : param.rawType

// add an ID to the child table so they can be linked to

slugger.reset()

const id = slugger.slug(`${param.name}-${parentType}`)

return {

parentName: param.name,

parentType,

id,

params: childParams

}

function createCodeBlock (input, language) {

// stringify JSON if needed

if (language === 'json' && typeof input !== 'string') {

input = JSON.stringify(input, null, 2)

}

return ['```' + language, input, '```'].join('\n')

}

github-docs/script/rest/utils/operation.js at main · 0xdevalias/github-docs · GitHub

Expand file tree

Breadcrumbs

operation.js

Latest commit

History

Breadcrumbs

operation.js

File metadata and controls