diff --git a/examples/docs/abstract.schema.md b/examples/docs/abstract.schema.md index 8782a9d187859d6cd4e78fb3ffd494b9bb3d2db5..b9753b81bb245b53b728557c11239ac4f9b1ce29 100644 --- a/examples/docs/abstract.schema.md +++ b/examples/docs/abstract.schema.md @@ -22,16 +22,16 @@ This is an abstract schema. It has `definitions`, but does not declare any prope | [foo](#foo) | `string` | `#/definitions/first` | | [bar](#bar) | `string` | `#/definitions/second` | -## foo +## bar A unique identifier given to every addressable thing. -`foo` +`bar` * is optional * type: `string` * defined in this schema -### foo Type +### bar Type `string` @@ -41,16 +41,16 @@ A unique identifier given to every addressable thing. -## bar +## foo A unique identifier given to every addressable thing. -`bar` +`foo` * is optional * type: `string` * defined in this schema -### bar Type +### foo Type `string` diff --git a/examples/docs/arrays.schema.md b/examples/docs/arrays.schema.md index 2b9a7ead1e2d1ab416008c3d2be8963c351b692e..e4f9f73dbeb0bdcf40c8cf6fd5b378828f443d1b 100644 --- a/examples/docs/arrays.schema.md +++ b/examples/docs/arrays.schema.md @@ -27,25 +27,23 @@ This is an example schema with examples for multiple array types and their const | [numlist](#numlist) | `number[]` | Optional | Arrays (this schema) | | [stringlistlist](#stringlistlist) | `string[][]` | Optional | Arrays (this schema) | -## list +## boollist This is an array -`list` +`boollist` * is optional -* type: `string[]` - +* type: `boolean[]` +* at least `1` items in the array * defined in this schema -### list Type +### boollist Type -Array type: `string[]` +Array type: `boolean[]` All items must be of the type: -`string` - - +`boolean` @@ -53,51 +51,57 @@ All items must be of the type: -## listlist +## coordinatelist -This is an array of arrays +This is an array of coordinates in three-dimensional space. -`listlist` +`coordinatelist` * is optional -* type: `array[]` (nested array) - +* type: `number[][]` (nested array) +* no more than `10` items in the array * defined in this schema -### listlist Type - +### coordinatelist Type -Nested array type: `array` +Nested array type: `number[]` +All items must be of the type: +`number` +* minimum value: `0` +* maximum value: `10` + +A coordinate, specified by `x`, `y`, and `z` values -## stringlistlist -This is an array of arrays of strings -`stringlistlist` -* is optional -* type: `string[][]` (nested array) -* defined in this schema -### stringlistlist Type +## intlist -Nested array type: `string[]` +This is an array +`intlist` +* is optional +* type: `integer[]` +* between `1` and `10` items in the array +* defined in this schema +### intlist Type -All items must be of the type: -`string` +Array type: `integer[]` +All items must be of the type: +`integer` @@ -107,23 +111,23 @@ All items must be of the type: -## intlist +## list This is an array -`intlist` +`list` * is optional -* type: `integer[]` -* between `1` and `10` items in the array +* type: `string[]` + * defined in this schema -### intlist Type +### list Type -Array type: `integer[]` +Array type: `string[]` All items must be of the type: -`integer` +`string` @@ -133,23 +137,23 @@ All items must be of the type: -## boollist +## listlist -This is an array +This is an array of arrays -`boollist` +`listlist` * is optional -* type: `boolean[]` -* at least `1` items in the array +* type: `array[]` (nested array) + * defined in this schema -### boollist Type +### listlist Type + + +Nested array type: `array` -Array type: `boolean[]` -All items must be of the type: -`boolean` @@ -183,33 +187,29 @@ All items must be of the type: -## coordinatelist +## stringlistlist -This is an array of coordinates in three-dimensional space. +This is an array of arrays of strings -`coordinatelist` +`stringlistlist` * is optional -* type: `number[][]` (nested array) -* no more than `10` items in the array +* type: `string[][]` (nested array) + * defined in this schema -### coordinatelist Type +### stringlistlist Type -Nested array type: `number[]` +Nested array type: `string[]` All items must be of the type: -`number` -* minimum value: `0` -* maximum value: `10` +`string` - -A coordinate, specified by `x`, `y`, and `z` values diff --git a/examples/docs/complex.schema.md b/examples/docs/complex.schema.md index a472feef4ada09706f63f27101d177c8171a566c..a56c0693ea025b65e4c54a0f9d816fdd24ba158f 100644 --- a/examples/docs/complex.schema.md +++ b/examples/docs/complex.schema.md @@ -32,142 +32,142 @@ This is an example schema that uses types defined in other schemas. | [refnamed](#refnamed) | Simple | Optional | Complex References (this schema) | | [xor](#xor) | complex | Optional | Complex References (this schema) | -## refabstract - +## and +Number in a range -`refabstract` -* is **required** +`and` +* is optional * type: complex * defined in this schema -### refabstract Type +### and Type -Unknown type ``. -```json -{ - "properties": { - "foo": { - "type": "string", - "description": "A unique identifier given to every addressable thing." - } - }, - "required": true, - "simpletype": "complex" -} -``` +**All** of the following *requirements* need to be fulfilled. +#### Requirement 1 +`number` +* maximum value: `10` -## refnamed +#### Requirement 2 -`refnamed` -* is optional -* type: Simple -* defined in this schema +`number` +* minimum value: `0` -### refnamed Type -* [Simple](simple.schema.md) – `https://example.com/schemas/simple` +## or -## reflist +String or number… +`or` +* is optional +* type: complex +* defined in this schema +### or Type -`reflist` -* is optional -* type: Simple -* defined in this schema +**Any** following *options* needs to be fulfilled. -### reflist Type +#### Option 1 -Array type: Simple -All items must be of the type: -* [Simple](simple.schema.md) – `https://example.com/schemas/simple` +`string` +#### Option 2 +`number` +* minimum value: `0` -## or -String or number… -`or` -* is optional -* type: complex -* defined in this schema -### or Type +## refabstract -**Any** following *options* needs to be fulfilled. -#### Option 1 +`refabstract` +* is **required** +* type: complex +* defined in this schema +### refabstract Type -`string` +Unknown type ``. +```json +{ + "properties": { + "foo": { + "type": "string", + "description": "A unique identifier given to every addressable thing." + } + }, + "required": true, + "simpletype": "complex" +} +``` -#### Option 2 -`number` -* minimum value: `0` +## reflist +`reflist` +* is optional +* type: Simple +* defined in this schema +### reflist Type -## and -Number in a range +Array type: Simple -`and` -* is optional -* type: complex -* defined in this schema +All items must be of the type: +* [Simple](simple.schema.md) – `https://example.com/schemas/simple` -### and Type -**All** of the following *requirements* need to be fulfilled. -#### Requirement 1 -`number` -* maximum value: `10` +## refnamed -#### Requirement 2 -`number` -* minimum value: `0` +`refnamed` +* is optional +* type: Simple +* defined in this schema + +### refnamed Type +* [Simple](simple.schema.md) – `https://example.com/schemas/simple` diff --git a/examples/docs/custom.schema.md b/examples/docs/custom.schema.md index bfcdfc2e4f7c3bac0bd4f5b3f1b6abe4537c0dea..de9cb6407c61cdf2df4739d02e124506171e081e 100644 --- a/examples/docs/custom.schema.md +++ b/examples/docs/custom.schema.md @@ -22,16 +22,16 @@ This is an extensible schema. It has `definitions`, that can be used in other sc | [bar](#bar) | `string` | Optional | Custom (this schema) | | [foo](#foo) | `string` | Optional | Custom (this schema) | -## foo +## bar A unique identifier given to every addressable thing. -`foo` +`bar` * is optional * type: `string` * defined in this schema -### foo Type +### bar Type `string` @@ -41,16 +41,16 @@ A unique identifier given to every addressable thing. -## bar +## foo A unique identifier given to every addressable thing. -`bar` +`foo` * is optional * type: `string` * defined in this schema -### bar Type +### foo Type `string` diff --git a/examples/docs/deepextending.schema.md b/examples/docs/deepextending.schema.md index cf4a22cb71b21bdfcd86e1f2f1de33d27a6a41ad..2b8f2dd3f6ec884d3a3958e5f09a2fb67a8aa7ff 100644 --- a/examples/docs/deepextending.schema.md +++ b/examples/docs/deepextending.schema.md @@ -61,26 +61,6 @@ A horse walks into it. -## id - -A unique identifier given to every addressable thing. - -`id` -* is optional -* type: `string` -* defined in [Definitions](definitions.schema.md#id) - -### id Type - - -`string` -* format: `uri` Uniformous Resource Identifier (according to [RFC3986](http://tools.ietf.org/html/rfc3986)) - - - - - - ## baz ### BAAAZ! @@ -125,3 +105,23 @@ A unique identifier given to every addressable thing. + +## id + +A unique identifier given to every addressable thing. + +`id` +* is optional +* type: `string` +* defined in [Definitions](definitions.schema.md#id) + +### id Type + + +`string` +* format: `uri` Uniformous Resource Identifier (according to [RFC3986](http://tools.ietf.org/html/rfc3986)) + + + + + diff --git a/examples/docs/example.schema.md b/examples/docs/example.schema.md index 606cf64c1452252ef8d53fae3a17ee4ef440d52d..a72db9642b4c76dc940a22c9f4a32a4e4cd34ec8 100644 --- a/examples/docs/example.schema.md +++ b/examples/docs/example.schema.md @@ -30,16 +30,16 @@ This is an example schema with examples. Too many examples? There can never be t | [bar](#bar) | `string` | Optional | Example (this schema) | | [foo](#foo) | `string` | Optional | Example (this schema) | -## foo +## bar A simple string. -`foo` +`bar` * is optional * type: `string` * defined in this schema -### foo Type +### bar Type `string` @@ -48,23 +48,28 @@ A simple string. -### foo Example +### bar Examples ```json "bar" ``` +```json +"baz" +``` + -## bar + +## foo A simple string. -`bar` +`foo` * is optional * type: `string` * defined in this schema -### bar Type +### foo Type `string` @@ -73,14 +78,9 @@ A simple string. -### bar Examples +### foo Example ```json "bar" ``` -```json -"baz" -``` - - diff --git a/examples/docs/examples.schema.md b/examples/docs/examples.schema.md index d1fc3195972d2c2b1cb65bcde55e1ee41cbae410..6195d44b6c2389924900749ac2055f2d93a47515 100644 --- a/examples/docs/examples.schema.md +++ b/examples/docs/examples.schema.md @@ -39,16 +39,16 @@ This is an example schema with *multiple* examples. Too many examples? There can | [bar](#bar) | `string` | **Required** | Examples (this schema) | | [foo](#foo) | `string` | Optional | Examples (this schema) | -## foo +## bar A simple string. -`foo` -* is optional +`bar` +* is **required** * type: `string` * defined in this schema -### foo Type +### bar Type `string` @@ -57,23 +57,28 @@ A simple string. -### foo Example +### bar Examples ```json "bar" ``` +```json +"baz" +``` + -## bar + +## foo A simple string. -`bar` -* is **required** +`foo` +* is optional * type: `string` * defined in this schema -### bar Type +### foo Type `string` @@ -82,14 +87,9 @@ A simple string. -### bar Examples +### foo Example ```json "bar" ``` -```json -"baz" -``` - - diff --git a/examples/docs/extending.schema.md b/examples/docs/extending.schema.md index e7ce068f62f2d9460f928f8ab80058416e52a9e9..eea0dd7af0b23ddd852e4e704d27c626b8856f2d 100644 --- a/examples/docs/extending.schema.md +++ b/examples/docs/extending.schema.md @@ -59,48 +59,48 @@ A horse walks into it. -## id +## baz +### BAAAZ! -A unique identifier given to every addressable thing. +This property has a unique name to demonstrate it's uniqueness. -`id` +`baz` * is optional * type: `string` -* defined in [Definitions](definitions.schema.md#id) +* defined in this schema -### id Type +### baz Type `string` -* format: `uri` Uniformous Resource Identifier (according to [RFC3986](http://tools.ietf.org/html/rfc3986)) +### baz Example -## baz -### BAAAZ! +```json +"I'm just a humble example" +``` -This property has a unique name to demonstrate it's uniqueness. -`baz` +## id + +A unique identifier given to every addressable thing. + +`id` * is optional * type: `string` -* defined in this schema +* defined in [Definitions](definitions.schema.md#id) -### baz Type +### id Type `string` +* format: `uri` Uniformous Resource Identifier (according to [RFC3986](http://tools.ietf.org/html/rfc3986)) -### baz Example - -```json -"I'm just a humble example" -``` - diff --git a/examples/docs/extensible.schema.md b/examples/docs/extensible.schema.md index 889086ffc2ee64bf829880d0d265891ed16fbd3a..9d90134a9aa84e867acecf013c74676a85dc3ad5 100644 --- a/examples/docs/extensible.schema.md +++ b/examples/docs/extensible.schema.md @@ -22,16 +22,16 @@ This is an extensible schema. It has `definitions`, that can be used in other sc | [foo](#foo) | `string` | `#/definitions/first` | | [bar](#bar) | `string` | `#/definitions/second` | -## foo +## bar -A unique identifier given to every addressable thing. +A horse walks into it. -`foo` +`bar` * is optional * type: `string` * defined in this schema -### foo Type +### bar Type `string` @@ -40,23 +40,28 @@ A unique identifier given to every addressable thing. -### foo Example +### bar Examples ```json -"bar" +"whoo" ``` +```json +"hoo" +``` -## bar -A horse walks into it. -`bar` +## foo + +A unique identifier given to every addressable thing. + +`foo` * is optional * type: `string` * defined in this schema -### bar Type +### foo Type `string` @@ -65,14 +70,9 @@ A horse walks into it. -### bar Examples - -```json -"whoo" -``` +### foo Example ```json -"hoo" +"bar" ``` - diff --git a/examples/docs/simpletypes.schema.md b/examples/docs/simpletypes.schema.md index 37f8deba8b716b0d8b4356782c3d1e010f85c52f..b2e1614a058916c2d4544384ba41578eec84b865 100644 --- a/examples/docs/simpletypes.schema.md +++ b/examples/docs/simpletypes.schema.md @@ -37,174 +37,102 @@ This is an example schema with examples for multiple types and their constraints | [string_uri](#string_uri) | `string` | Optional | Simple Types (this schema) | | [yesno](#yesno) | `boolean` | **Required** | Simple Types (this schema) | -## string_unconstrained +## integer_threes -A simple string, without any constraints. +Guess what number is valid -`string_unconstrained` +`integer_threes` * is optional -* type: `string` +* type: `integer` * defined in this schema -### string_unconstrained Type - +### integer_threes Type -`string` +`integer` +* minimum value: `2` +* maximum value: `4` +* must be a multiple of `3` -### string_unconstrained Example -```json -"bar" -``` - - -## string_length +## interger_constrained -A string with minumum and maximum length +Just a whole number. I don't like fractions. Don't get too small -`string_length` +`interger_constrained` * is optional -* type: `string` +* type: `integer` * defined in this schema -### string_length Type - - -`string` -* minimum length: 3 characters -* maximum length: 3 characters +### interger_constrained Type +`integer` +* minimum value: `10` -### string_length Examples -```json -"bar" -``` -```json -"baz" -``` -## string_pattern +## interger_unconstrained -A string following a regular expression +Just a whole number. I don't like fractions. -`string_pattern` +`interger_unconstrained` * is optional -* type: `string` +* type: `integer` * defined in this schema -### string_pattern Type - - -`string` - - -All instances must conform to this regular expression -```regex -^ba.$ -``` - -* test example: [bar](https://regexr.com/?expression=%5Eba.%24&text=bar) -* test example: [baz](https://regexr.com/?expression=%5Eba.%24&text=baz) -* test example: [bat](https://regexr.com/?expression=%5Eba.%24&text=bat) - - -### string_pattern Known Values -| Value | Description | -|-------|-------------| -| `baa` | the sounds of sheeps | -| `bad` | German bathroom | -| `bag` | holding device | -| `bah` | humbug! | -| `bam` | a loud sound | -| `ban` | don't do this | -| `bap` | a British soft bread roll | -| `bas` | from ancient Egyptian religion, an aspect of the soul | -| `bat` | …out of hell | -| `bay` | , sitting by the dock of the | +### interger_unconstrained Type +`integer` -### string_pattern Examples -```json -"bar" -``` -```json -"baz" -``` - -```json -"bat" -``` -## string_pattern_noexample +## number_constrained -A string following a regular expression +Just a number. Don't get too big. -`string_pattern_noexample` +`number_constrained` * is optional -* type: `string` +* type: `number` * defined in this schema -### string_pattern_noexample Type - - -`string` +### number_constrained Type -All instances must conform to this regular expression -(test examples [here](https://regexr.com/?expression=%5Eba.%24)): -```regex -^ba.$ -``` - +`number` +* value must not be greater or equal than: `10` -## string_pattern_singleexample +## number_unconstrained -A string following a regular expression +Just a number -`string_pattern_singleexample` +`number_unconstrained` * is optional -* type: `string` +* type: `number` * defined in this schema -### string_pattern_singleexample Type - - -`string` - - -All instances must conform to this regular expression -```regex -^ba.$ -``` +### number_unconstrained Type -* test example: [bar](https://regexr.com/?expression=%5Eba.%24&text=bar) +`number` -### string_pattern_singleexample Example -```json -"bar" -``` ## string_date @@ -307,119 +235,191 @@ An IPv6-like string. -## string_uri +## string_length -A URI. +A string with minumum and maximum length -`string_uri` +`string_length` * is optional * type: `string` * defined in this schema -### string_uri Type +### string_length Type `string` -* format: `uri` Uniformous Resource Identifier (according to [RFC3986](http://tools.ietf.org/html/rfc3986)) +* minimum length: 3 characters +* maximum length: 3 characters +### string_length Examples +```json +"bar" +``` +```json +"baz" +``` -## number_unconstrained -Just a number -`number_unconstrained` +## string_pattern + +A string following a regular expression + +`string_pattern` * is optional -* type: `number` +* type: `string` * defined in this schema -### number_unconstrained Type +### string_pattern Type -`number` +`string` + + +All instances must conform to this regular expression +```regex +^ba.$ +``` + +* test example: [bar](https://regexr.com/?expression=%5Eba.%24&text=bar) +* test example: [baz](https://regexr.com/?expression=%5Eba.%24&text=baz) +* test example: [bat](https://regexr.com/?expression=%5Eba.%24&text=bat) +### string_pattern Known Values +| Value | Description | +|-------|-------------| +| `baa` | the sounds of sheeps | +| `bad` | German bathroom | +| `bag` | holding device | +| `bah` | humbug! | +| `bam` | a loud sound | +| `ban` | don't do this | +| `bap` | a British soft bread roll | +| `bas` | from ancient Egyptian religion, an aspect of the soul | +| `bat` | …out of hell | +| `bay` | , sitting by the dock of the | +### string_pattern Examples -## interger_unconstrained +```json +"bar" +``` -Just a whole number. I don't like fractions. +```json +"baz" +``` -`interger_unconstrained` +```json +"bat" +``` + + + +## string_pattern_noexample + +A string following a regular expression + +`string_pattern_noexample` * is optional -* type: `integer` +* type: `string` * defined in this schema -### interger_unconstrained Type +### string_pattern_noexample Type -`integer` +`string` +All instances must conform to this regular expression +(test examples [here](https://regexr.com/?expression=%5Eba.%24)): +```regex +^ba.$ +``` -## interger_constrained -Just a whole number. I don't like fractions. Don't get too small -`interger_constrained` +## string_pattern_singleexample + +A string following a regular expression + +`string_pattern_singleexample` * is optional -* type: `integer` +* type: `string` * defined in this schema -### interger_constrained Type +### string_pattern_singleexample Type -`integer` -* minimum value: `10` +`string` + + +All instances must conform to this regular expression +```regex +^ba.$ +``` +* test example: [bar](https://regexr.com/?expression=%5Eba.%24&text=bar) +### string_pattern_singleexample Example -## number_constrained +```json +"bar" +``` -Just a number. Don't get too big. -`number_constrained` +## string_unconstrained + +A simple string, without any constraints. + +`string_unconstrained` * is optional -* type: `number` +* type: `string` * defined in this schema -### number_constrained Type +### string_unconstrained Type -`number` -* value must not be greater or equal than: `10` +`string` -## integer_threes +### string_unconstrained Example -Guess what number is valid +```json +"bar" +``` -`integer_threes` + +## string_uri + +A URI. + +`string_uri` * is optional -* type: `integer` +* type: `string` * defined in this schema -### integer_threes Type +### string_uri Type -`integer` -* minimum value: `2` -* maximum value: `4` -* must be a multiple of `3` +`string` +* format: `uri` Uniformous Resource Identifier (according to [RFC3986](http://tools.ietf.org/html/rfc3986)) + diff --git a/lib/markdownWriter.js b/lib/markdownWriter.js index bd1a3fc9451f11691cfe9aaf1bc1ded9cb63da80..00ba80de824d389d7b557de25c51223da82f696e 100644 --- a/lib/markdownWriter.js +++ b/lib/markdownWriter.js @@ -174,12 +174,13 @@ const generateMarkdown = function(filename, schema, schemaPath, outDir, dependen if (_.keys(schema.properties).length > 0) { multi.push([ 'properties.ejs', { props: requiredProperties(schema.properties, schema.required), title: schema.title } ]); for (let i=0; i<_.keys(schema.properties).length;i++) { + const name = _.keys(schema.properties).sort()[i]; multi.push( [ 'property.ejs', { - name: _.keys(schema.properties)[i], - required: schema.required ? schema.required.includes(_.keys(schema.properties)[i]) : false, - examples: stringifyExamples(schema.properties[_.keys(schema.properties)[i]]['examples']), + name: name, + required: schema.required ? schema.required.includes(name) : false, + examples: stringifyExamples(schema.properties[name]['examples']), ejs: ejsRender, - schema: simpletype(schema.properties[_.keys(schema.properties)[i]]) } ]); + schema: simpletype(schema.properties[name]) } ]); } } //find definitions that contain properties that are not part of the main schema @@ -203,12 +204,13 @@ const generateMarkdown = function(filename, schema, schemaPath, outDir, dependen //console.log('I got definitions!', abstract); multi.push([ 'definitions.ejs', { props: requiredProperties(abstract), title: schema.title } ]); for (let i=0; i<_.keys(abstract).length;i++) { + const name = _.keys(abstract).sort()[i]; multi.push( [ 'property.ejs', { - name: _.keys(abstract)[i], + name: name, required: false, ejs: ejsRender, - examples: stringifyExamples(abstract[_.keys(abstract)[i]]['examples']), - schema: simpletype(abstract[_.keys(abstract)[i]]) } ]); + examples: stringifyExamples(abstract[name]['examples']), + schema: simpletype(abstract[name]) } ]); } } }