-
Notifications
You must be signed in to change notification settings - Fork 87
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
feat: validate x-sdk-operations extension
Changes: - add custom Spectral rule to validate x-sdk-operations - add custom Spectral function to invoke ajv JSON Schema validator on x-sdk-operations JSON Schema Tests: - ensure warnings issued for invalid x-sdk-operations schema Docs: - document `ibm-sdk-operations` rule
- Loading branch information
Barrett Schonefeld
committed
Mar 30, 2021
1 parent
fd34717
commit 92faa49
Showing
4 changed files
with
212 additions
and
2 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,118 @@ | ||
const AJV = require('ajv'); | ||
const ajv = new AJV({ allErrors: true, jsonPointers: true }); | ||
const jsonSchema = { | ||
$schema: 'http://json-schema.org/draft-07/schema#', | ||
title: 'IBM SDK Operations Extension', | ||
description: 'sdk operations extension schema', | ||
properties: { | ||
'x-sdk-operations': { | ||
properties: { | ||
'request-examples': { | ||
additionalProperties: { | ||
$ref: '#/definitions/x-sdk-request-examples-array' | ||
} | ||
} | ||
}, | ||
additionalProperties: false | ||
} | ||
}, | ||
definitions: { | ||
'x-sdk-request-examples-array': { | ||
type: 'array', | ||
items: { | ||
$ref: '#/definitions/x-sdk-request-example' | ||
} | ||
}, | ||
'x-sdk-request-example': { | ||
properties: { | ||
name: { | ||
type: 'string', | ||
description: | ||
'The name or title of the example. In documentation it should appear as a header above the example.' | ||
}, | ||
contentType: { | ||
type: 'array', | ||
items: { | ||
type: 'string', | ||
description: 'The media type of the response in this example.' | ||
} | ||
}, | ||
example: { | ||
type: 'array', | ||
description: | ||
'An array of code or text elements that make up the example', | ||
items: { | ||
$ref: '#/definitions/x-sdk-request-example-element' | ||
} | ||
}, | ||
response: {}, | ||
description: { | ||
type: 'string' | ||
} | ||
}, | ||
required: ['name', 'example'], | ||
additionalProperties: false | ||
}, | ||
'x-sdk-request-example-element': { | ||
description: 'An element of the request example.', | ||
properties: { | ||
name: { | ||
type: 'string', | ||
description: | ||
'The name or title of the example element. In documentation it should appear as a header above the example element.' | ||
}, | ||
type: { | ||
type: 'string', | ||
description: | ||
'The element type indicates the type of content in the element. `text` elements contain a textual description or explanation, possibly using markdown for rich text elements. `code` elements contain code appropriate for the language of the request example. `code` elements will be presented in a `<pre><code>` block in documentation and should contain no markup or escapes other than escapes for quote and backslash (required for JSON).', | ||
enum: ['text', 'code'] | ||
}, | ||
source: { | ||
type: 'array', | ||
items: { | ||
type: 'string' | ||
}, | ||
description: | ||
'Content of the example element as an array of strings. The content is formed by simple concatenation of the array elements.' | ||
} | ||
}, | ||
required: ['type', 'source'] | ||
} | ||
} | ||
}; | ||
|
||
module.exports = function(sdkOperations, _opts, paths) { | ||
const errors = []; | ||
const sdkSchema = { | ||
'x-sdk-operations': sdkOperations | ||
}; | ||
const rootPath = paths.target !== void 0 ? paths.target : paths.given; | ||
const validate = ajv.compile(jsonSchema); | ||
if (!ajv.validate(jsonSchema, sdkSchema)) { | ||
return formatAJVErrors(validate.errors, rootPath); | ||
} | ||
return errors; | ||
}; | ||
|
||
function formatAJVErrors(errors, rootPath) { | ||
const errorList = []; | ||
errors.forEach(function(err) { | ||
errorList.push({ | ||
message: err.message, | ||
path: getErrPath(err, rootPath) | ||
}); | ||
}); | ||
return errorList; | ||
} | ||
|
||
function getErrPath(err, rootPath) { | ||
const relativePath = err.dataPath.split('/'); | ||
if (relativePath.length > 1) { | ||
const strippedPath = relativePath.splice( | ||
relativePath.indexOf('x-sdk-operations') + 1, | ||
relativePath.length | ||
); | ||
return [...rootPath, ...strippedPath]; | ||
} | ||
return rootPath; | ||
} |
53 changes: 53 additions & 0 deletions
53
test/spectral/tests/custom-rules/ibm-sdk-operations.test.js
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,53 @@ | ||
const inCodeValidator = require('../../../../src/lib'); | ||
|
||
describe('spectral - test that x-sdk-operations schema violations cause errors', function() { | ||
let res; | ||
|
||
beforeAll(async () => { | ||
const spec = { | ||
openapi: '3.0.0', | ||
info: { | ||
version: '1.0.0', | ||
title: 'ErrorAPI' | ||
}, | ||
servers: [{ url: 'http://api.errorapi.com/v1' }], | ||
paths: { | ||
path1: { | ||
post: { | ||
'x-sdk-operations': { | ||
'request-examples': { | ||
type: 13, | ||
notafield: 'asdf' | ||
} | ||
} | ||
} | ||
} | ||
} | ||
}; | ||
|
||
res = await inCodeValidator(spec, true); | ||
}); | ||
|
||
it('should warn for invalid x-sdk-operations schema', function() { | ||
const expectedWarnings = res.warnings.filter( | ||
warn => warn.rule === 'ibm-sdk-operations' | ||
); | ||
expect(expectedWarnings.length).toBe(2); | ||
expect(expectedWarnings[0].path).toEqual([ | ||
'paths', | ||
'path1', | ||
'post', | ||
'x-sdk-operations', | ||
'request-examples', | ||
'type' | ||
]); | ||
expect(expectedWarnings[1].path).toEqual([ | ||
'paths', | ||
'path1', | ||
'post', | ||
'x-sdk-operations', | ||
'request-examples', | ||
'notafield' | ||
]); | ||
}); | ||
}); |