From 6027ba375b14626c82adea6ae9f19b3e8cbe75a4 Mon Sep 17 00:00:00 2001
From: Lars Trieloff <trieloff@adobe.com>
Date: Thu, 14 Dec 2017 14:26:47 +0000
Subject: [PATCH] #5 support enums
---
examples/docs/README.md | 1 +
examples/docs/constants.schema.md | 5 --
examples/docs/custom.schema.md | 12 ---
examples/docs/deepextending.schema.md | 21 -----
examples/docs/definitions.schema.md | 5 --
examples/docs/enums.schema.md | 42 +++++++++
examples/docs/example.schema.md | 10 ---
examples/docs/examples.schema.md | 10 ---
examples/docs/extending.schema.md | 15 ----
examples/docs/simple.schema.md | 5 --
examples/docs/simpletypes.schema.md | 89 --------------------
examples/generated-schemas/enums.schema.json | 26 ++++++
examples/schemas/enums.schema.json | 23 +++++
lib/markdownWriter.js | 13 ++-
templates/md/property.ejs | 14 +--
15 files changed, 113 insertions(+), 178 deletions(-)
create mode 100644 examples/docs/enums.schema.md
create mode 100644 examples/generated-schemas/enums.schema.json
create mode 100644 examples/schemas/enums.schema.json
diff --git a/examples/docs/README.md b/examples/docs/README.md
index ea96b3f..5c3bfe0 100644
--- a/examples/docs/README.md
+++ b/examples/docs/README.md
@@ -11,6 +11,7 @@
* [Custom](./custom.schema.md) – `https://example.com/schemas/custom`
* [Custom](./deepextending.schema.md) – `https://example.com/schemas/deepextending`
* [Definitions](./definitions.schema.md) – `https://example.com/schemas/definitions`
+* [Enumerated ](./enums.schema.md) – `https://example.com/schemas/enums`
* [Example](./example.schema.md) – `https://example.com/schemas/example`
* [Examples](./examples.schema.md) – `https://example.com/schemas/examples`
* [Extending](./extending.schema.md) – `https://example.com/schemas/extending`
diff --git a/examples/docs/constants.schema.md b/examples/docs/constants.schema.md
index 32320f0..518253c 100644
--- a/examples/docs/constants.schema.md
+++ b/examples/docs/constants.schema.md
@@ -36,11 +36,6 @@ The value of this property **must** be equal to:
"World"
```
-### Known Values
-| Value | Description |
-|-------|-------------|
-| `hi` | Welcome |
-| `bye` | Farewell |
diff --git a/examples/docs/custom.schema.md b/examples/docs/custom.schema.md
index 8946877..f6f7b4b 100644
--- a/examples/docs/custom.schema.md
+++ b/examples/docs/custom.schema.md
@@ -38,12 +38,6 @@ A unique identifier given to every addressable thing.
-### Known Values
-
-| Value | Description |
-|-------|-------------|
-| `hi` | Welcome |
-| `bye` | Farewell |
@@ -63,11 +57,5 @@ A unique identifier given to every addressable thing.
-### Known Values
-
-| Value | Description |
-|-------|-------------|
-| `hi` | Welcome |
-| `bye` | Farewell |
diff --git a/examples/docs/deepextending.schema.md b/examples/docs/deepextending.schema.md
index f704d2c..6031d94 100644
--- a/examples/docs/deepextending.schema.md
+++ b/examples/docs/deepextending.schema.md
@@ -47,12 +47,7 @@ A horse walks into it.
-### Known Values
-| Value | Description |
-|-------|-------------|
-| `hi` | Welcome |
-| `bye` | Farewell |
### bar Examples
@@ -82,12 +77,7 @@ A unique identifier given to every addressable thing.
* format: `uri` Uniformous Resource Identifier (according to [RFC3986](http://tools.ietf.org/html/rfc3986))
-### Known Values
-| Value | Description |
-|-------|-------------|
-| `hi` | Welcome |
-| `bye` | Farewell |
@@ -108,12 +98,7 @@ This property has a unique name to demonstrate it's uniqueness.
-### Known Values
-| Value | Description |
-|-------|-------------|
-| `hi` | Welcome |
-| `bye` | Farewell |
### baz Example
@@ -138,11 +123,5 @@ A unique identifier given to every addressable thing.
-### Known Values
-
-| Value | Description |
-|-------|-------------|
-| `hi` | Welcome |
-| `bye` | Farewell |
diff --git a/examples/docs/definitions.schema.md b/examples/docs/definitions.schema.md
index 4c012da..32326e0 100644
--- a/examples/docs/definitions.schema.md
+++ b/examples/docs/definitions.schema.md
@@ -38,11 +38,6 @@ A unique identifier given to every addressable thing.
* format: `uri` Uniformous Resource Identifier (according to [RFC3986](http://tools.ietf.org/html/rfc3986))
-### Known Values
-| Value | Description |
-|-------|-------------|
-| `hi` | Welcome |
-| `bye` | Farewell |
diff --git a/examples/docs/enums.schema.md b/examples/docs/enums.schema.md
new file mode 100644
index 0000000..0cf5a9c
--- /dev/null
+++ b/examples/docs/enums.schema.md
@@ -0,0 +1,42 @@
+---
+template: reference
+foo: bar
+---
+
+# Enumerated Schema
+
+```
+https://example.com/schemas/enums
+```
+
+This is an example schema with examples for properties with enum values
+
+| Abstract | Extensible | Custom Properties | Defined In |
+|----------|------------|-------------------|------------|
+| Can be instantiated | No | Forbidden | [enums.schema.json](enums.schema.json) |
+
+# Enumerated Properties
+
+| Property | Type | Required | Defined by |
+|----------|------|----------|------------|
+| [hello](#hello) | `enum` | **Required** | Enumerated (this schema) |
+
+## hello
+
+A simple string. Pick a value.
+
+`hello`
+* is **required**
+* type: `enum`
+* defined in this schema
+
+The value of this property **must** be equal to one of the known values below.
+
+### hello Known Values
+| Value | Description |
+|-------|-------------|
+| `World` | |
+| `Welt` | |
+
+
+
diff --git a/examples/docs/example.schema.md b/examples/docs/example.schema.md
index 1d65f33..5385085 100644
--- a/examples/docs/example.schema.md
+++ b/examples/docs/example.schema.md
@@ -46,12 +46,7 @@ A simple string.
-### Known Values
-| Value | Description |
-|-------|-------------|
-| `hi` | Welcome |
-| `bye` | Farewell |
### foo Example
@@ -76,12 +71,7 @@ A simple string.
-### Known Values
-| Value | Description |
-|-------|-------------|
-| `hi` | Welcome |
-| `bye` | Farewell |
### bar Examples
diff --git a/examples/docs/examples.schema.md b/examples/docs/examples.schema.md
index 7f349b3..9b44b8d 100644
--- a/examples/docs/examples.schema.md
+++ b/examples/docs/examples.schema.md
@@ -55,12 +55,7 @@ A simple string.
-### Known Values
-| Value | Description |
-|-------|-------------|
-| `hi` | Welcome |
-| `bye` | Farewell |
### foo Example
@@ -85,12 +80,7 @@ A simple string.
-### Known Values
-| Value | Description |
-|-------|-------------|
-| `hi` | Welcome |
-| `bye` | Farewell |
### bar Examples
diff --git a/examples/docs/extending.schema.md b/examples/docs/extending.schema.md
index 74d40d4..bc33bde 100644
--- a/examples/docs/extending.schema.md
+++ b/examples/docs/extending.schema.md
@@ -45,12 +45,7 @@ A horse walks into it.
-### Known Values
-| Value | Description |
-|-------|-------------|
-| `hi` | Welcome |
-| `bye` | Farewell |
### bar Examples
@@ -80,12 +75,7 @@ A unique identifier given to every addressable thing.
* format: `uri` Uniformous Resource Identifier (according to [RFC3986](http://tools.ietf.org/html/rfc3986))
-### Known Values
-| Value | Description |
-|-------|-------------|
-| `hi` | Welcome |
-| `bye` | Farewell |
@@ -106,12 +96,7 @@ This property has a unique name to demonstrate it's uniqueness.
-### Known Values
-| Value | Description |
-|-------|-------------|
-| `hi` | Welcome |
-| `bye` | Farewell |
### baz Example
diff --git a/examples/docs/simple.schema.md b/examples/docs/simple.schema.md
index c1cc268..922088c 100644
--- a/examples/docs/simple.schema.md
+++ b/examples/docs/simple.schema.md
@@ -37,11 +37,6 @@ A unique identifier given to every addressable thing.
* format: `uri` Uniformous Resource Identifier (according to [RFC3986](http://tools.ietf.org/html/rfc3986))
-### Known Values
-| Value | Description |
-|-------|-------------|
-| `hi` | Welcome |
-| `bye` | Farewell |
diff --git a/examples/docs/simpletypes.schema.md b/examples/docs/simpletypes.schema.md
index b6354de..1e087f3 100644
--- a/examples/docs/simpletypes.schema.md
+++ b/examples/docs/simpletypes.schema.md
@@ -53,12 +53,7 @@ A simple string, without any constraints.
-### Known Values
-| Value | Description |
-|-------|-------------|
-| `hi` | Welcome |
-| `bye` | Farewell |
### string_unconstrained Example
@@ -83,12 +78,7 @@ A string with minumum and maximum length
* minimum length: 3 characters
* maximum length: 3 characters
-### Known Values
-| Value | Description |
-|-------|-------------|
-| `hi` | Welcome |
-| `bye` | Farewell |
### string_length Examples
@@ -127,12 +117,7 @@ All instances must conform to this regular expression
* test example: [bat](https://regexr.com/?expression=%5Eba.%24&text=bat)
-### Known Values
-| Value | Description |
-|-------|-------------|
-| `hi` | Welcome |
-| `bye` | Farewell |
### string_pattern Examples
@@ -173,12 +158,6 @@ All instances must conform to this regular expression
-### Known Values
-
-| Value | Description |
-|-------|-------------|
-| `hi` | Welcome |
-| `bye` | Farewell |
@@ -205,12 +184,7 @@ All instances must conform to this regular expression
* test example: [bar](https://regexr.com/?expression=%5Eba.%24&text=bar)
-### Known Values
-| Value | Description |
-|-------|-------------|
-| `hi` | Welcome |
-| `bye` | Farewell |
### string_pattern_singleexample Example
@@ -235,12 +209,7 @@ A date-like string.
* format: `date-time` date and time (according to [RFC 3339, section 5.6](http://tools.ietf.org/html/rfc3339))
-### Known Values
-| Value | Description |
-|-------|-------------|
-| `hi` | Welcome |
-| `bye` | Farewell |
@@ -260,12 +229,7 @@ An email-like string.
* format: `email` email address (according to [RFC 5322, section 3.4.1](https://tools.ietf.org/html/rfc5322))
-### Known Values
-| Value | Description |
-|-------|-------------|
-| `hi` | Welcome |
-| `bye` | Farewell |
@@ -285,12 +249,7 @@ A hostname-like string.
* format: `hostname` Domain Name (according to [RFC 1034, section 3.1](https://tools.ietf.org/html/rfc1034))
-### Known Values
-| Value | Description |
-|-------|-------------|
-| `hi` | Welcome |
-| `bye` | Farewell |
@@ -310,12 +269,7 @@ An IPv4-like string.
* format: `ipv4` IP (v4) address (according to [RFC 2673, section 3.2](https://tools.ietf.org/html/rfc2673))
-### Known Values
-| Value | Description |
-|-------|-------------|
-| `hi` | Welcome |
-| `bye` | Farewell |
@@ -335,12 +289,7 @@ An IPv6-like string.
* format: `ipv6` IP (v6) address (according to [RFC 4291, section 2.2](https://tools.ietf.org/html/rfc4291))
-### Known Values
-| Value | Description |
-|-------|-------------|
-| `hi` | Welcome |
-| `bye` | Farewell |
@@ -360,12 +309,7 @@ A URI.
* format: `uri` Uniformous Resource Identifier (according to [RFC3986](http://tools.ietf.org/html/rfc3986))
-### Known Values
-| Value | Description |
-|-------|-------------|
-| `hi` | Welcome |
-| `bye` | Farewell |
@@ -385,12 +329,6 @@ Just a number
-### Known Values
-
-| Value | Description |
-|-------|-------------|
-| `hi` | Welcome |
-| `bye` | Farewell |
@@ -410,12 +348,6 @@ Just a whole number. I don't like fractions.
-### Known Values
-
-| Value | Description |
-|-------|-------------|
-| `hi` | Welcome |
-| `bye` | Farewell |
@@ -435,12 +367,7 @@ Just a whole number. I don't like fractions. Don't get too small
* minimum value: `10`
-### Known Values
-| Value | Description |
-|-------|-------------|
-| `hi` | Welcome |
-| `bye` | Farewell |
@@ -460,12 +387,6 @@ Just a number. Don't get too big.
* value must not be greater or equal than: `10`
-### Known Values
-
-| Value | Description |
-|-------|-------------|
-| `hi` | Welcome |
-| `bye` | Farewell |
@@ -486,12 +407,7 @@ Guess what number is valid
* maximum value: `4`
* must be a multiple of `3`
-### Known Values
-| Value | Description |
-|-------|-------------|
-| `hi` | Welcome |
-| `bye` | Farewell |
@@ -509,11 +425,6 @@ Guess what number is valid
`boolean`
-### Known Values
-| Value | Description |
-|-------|-------------|
-| `hi` | Welcome |
-| `bye` | Farewell |
diff --git a/examples/generated-schemas/enums.schema.json b/examples/generated-schemas/enums.schema.json
new file mode 100644
index 0000000..a11d21a
--- /dev/null
+++ b/examples/generated-schemas/enums.schema.json
@@ -0,0 +1,26 @@
+{
+ "meta:license": [
+ "Copyright 2017 Adobe Systems Incorporated. All rights reserved.",
+ "This file is licensed to you under the Apache License, Version 2.0 (the 'License');",
+ "you may not use this file except in compliance with the License. You may obtain a copy",
+ "of the License at http://www.apache.org/licenses/LICENSE-2.0"
+ ],
+ "$schema": "http://json-schema.org/draft-06/schema#",
+ "$id": "https://example.com/schemas/enums",
+ "title": "Enumerated ",
+ "type": "object",
+ "description": "This is an example schema with examples for properties with enum values",
+ "properties": {
+ "hello": {
+ "type": "string",
+ "enum": [
+ "World",
+ "Welt"
+ ],
+ "description": "A simple string. Pick a value."
+ }
+ },
+ "required": [
+ "hello"
+ ]
+}
\ No newline at end of file
diff --git a/examples/schemas/enums.schema.json b/examples/schemas/enums.schema.json
new file mode 100644
index 0000000..06f27bc
--- /dev/null
+++ b/examples/schemas/enums.schema.json
@@ -0,0 +1,23 @@
+{
+ "meta:license": [
+ "Copyright 2017 Adobe Systems Incorporated. All rights reserved.",
+ "This file is licensed to you under the Apache License, Version 2.0 (the 'License');",
+ "you may not use this file except in compliance with the License. You may obtain a copy",
+ "of the License at http://www.apache.org/licenses/LICENSE-2.0"
+ ],
+ "$schema": "http://json-schema.org/draft-06/schema#",
+ "$id": "https://example.com/schemas/enums",
+ "title": "Enumerated ",
+ "type": "object",
+ "description": "This is an example schema with examples for properties with enum values",
+ "properties": {
+ "hello": {
+ "type": "string",
+ "enum": ["World", "Welt"],
+ "description": "A simple string. Pick a value."
+ }
+ },
+ "required": [
+ "hello"
+ ]
+}
diff --git a/lib/markdownWriter.js b/lib/markdownWriter.js
index 2ad3140..32f3bf1 100644
--- a/lib/markdownWriter.js
+++ b/lib/markdownWriter.js
@@ -78,7 +78,18 @@ function stringifyExamples(examples) {
function simpletype(prop) {
const type = prop.type;
- if (prop.const!==undefined) {
+ if (prop.enum!==undefined) {
+ prop.simpletype = '`enum`';
+ if (prop['meta:enum']===undefined) {
+ prop['meta:enum'] = {};
+ }
+ for (let i=0;i<prop.enum.length;i++) {
+ if (prop['meta:enum'][prop.enum[i]]===undefined) {
+ //setting an empty description for each unknown enum
+ prop['meta:enum'][prop.enum[i]] = '';
+ }
+ }
+ } else if (prop.const!==undefined) {
prop.simpletype = '`const`';
} else if (type==='string') {
prop.simpletype = '`string`';
diff --git a/templates/md/property.ejs b/templates/md/property.ejs
index 3289130..f1b6fe1 100644
--- a/templates/md/property.ejs
+++ b/templates/md/property.ejs
@@ -25,6 +25,8 @@ The value of this property **must** be equal to:
<%- JSON.stringify(schema.const, null, 2) %>
```
+<% } else if (schema.enum!==undefined) { %>
+The value of this property **must** be equal to one of the known values below.
<% } else { %>
### <%=name %> Type
@@ -45,14 +47,16 @@ Unknown type `<%= schema.type %>`.
<% }} %>
-### Known Values
-
-
+<% if (schema.enum!==undefined||schema["meta:enum"]!==undefined) { %>
+### <%=name %> Known Values
| Value | Description |
|-------|-------------|
-| `hi` | Welcome |
-| `bye` | Farewell |
+<% _.forIn(schema["meta:enum"], (value, key, object) => { %>
+| `<%= key %>` | <%= value %> |
+<% }); %>
+
+<% } %>
<% if (examples && examples.length == 1) { %>
--
GitLab