JSON-Schema validation for json code blocks in your markdown files
npm install skeemas-markdown-validationjs
npm install skeemas-markdown-validation --save
`This will install skeemas-markdown-validation, and also install skeemas as a peerDependency if you haven't already installed it.
Usage
From within your markdown files you can provide relative links to schemas above each json code block:./docs.md:
My API Docs
Creating Foos
POST /foosRequest (see the new foo schema):
`json
{
"fooName": "johnson",
"fooAge": 35
}
`200 Response (see the foo schema):
`json
{
"id": "ffffffff-ffff-ffff-ffff-ffffffffffff",
"fooName": "johnson",
"fooAge": 35
}
`Array Docs
You can also document arrays using the "array-continuation" syntax (see the foo-list schema):
`json
[{
"id": "ffffffff-ffff-ffff-ffff-ffffffffffff",
"fooName": "johnson",
"fooAge": 35
}, {
"...": "Additional foos..."
}]
`Objects with a single property named
... will be removed from arrays before validation.
Add the plugin to
skeemas and then validate your markdown files:
`js
var skeemas = require('skeemas'),
skeemasMarkdownValidation = require('skeemas-markdown-validation');skeemas.use(skeemasMarkdownValidation);
// Use any test harness, validateMarkdown just throws errors on invalid json
describe('API Documentation -', function() {
it('main documentation should have correct JSON', function() {
// Validate your markdown
var validator = skeemas();
validator.validateMarkdown('./docs.md');
});
});
`For more examples look at the docs in our tests.
Running Independent Code Block Validations
If you use skeemas.validateMarkdown then an error will be thrown on the first case of invalid json. If you would prefer to see all the errors you have the option of running a test for each code block yourself:`js
var skeemas = require('skeemas'),
skeemasMarkdownValidation = require('skeemas-markdown-validation');skeemas.use(skeemasMarkdownValidation);
// Use any test harness, validateMarkdown just throws errors on invalid json
describe('API Documentation -', function() {
// Get an array containing test details for each json code block
var validator = skeemas(),
tests = validator.markdownTests('./docs.md');
tests.forEach(function(test) {
// Create a test case for each schema-linked json block
it('docs.md:' + test.json.line, test.execute.bind(test));
});
});
`
Using References
If you want to use $refs in your schemas you will need to create a schema validator instance and add your references to it:`js
var skeemas = require('skeemas'),
skeemasMarkdownValidation = require('skeemas-markdown-validation');skeemas.use(skeemasMarkdownValidation);
var validator = skeemas();
// Add a reference
validator.addRef('/foo-base', require('./schemas/foo-base.schema.json'));
// Validate your markdown
skeemas.validateMarkdown('./docs.md');
``