Webpack loader that transforms JSON HyperSchema (without $refs) into examples.
npm install json-schema-example-loaderWhile still used by the likewise-deprecated doca package, for the new @cloudflare/doca
package, this package has been replaced by @cloudflare/json-schema-apidoc-loader in
the json-schema-tools repository.
It relies on several general-purpose JSON Schema utility packages that are also present
in that repository.
Unlike json-schema-example-loader, the output of @cloudflare/json-schema-apidoc-loader is
still a valid JSON Schema, with extensions.
-------
This package is part of the doca suite. Please file any issues at the doca repository
``
npm install json-schema-example-loader --save
Webpack loader that transforms JSON HyperSchema (without $refs) into an updated datastructure that contains examples and simplified definitions that you can use in order to create nice API docs. Some original properties are removed and some new are precomputed and added (see bellow).
Why is this a webpack loader and not part of the app?
- JSON HyperSchema structure can be quite complex (deeply nested)
- We precompute a flat datastructure that better fits our UI components
- Everything can be nicely preformatted
- PERFORMANCE
Do you have references ($ref) in your schemas? Use json-schema-loader first.
`js`
var transformedSchema = require('json-schema-example-loader!./schema.json');
Or define it in your webpack.config.js
`js`
module: {
loaders: [{
test: /\.json$/,
exclude: /node_modules/,
loader: 'json-schema-example-loader'
}]
}
`js`
var transformedSchema = require('./schema.json');
`json`
{
"id": "https://api.example.com/product",
"$schema": "http://json-schema.org/draft-04/hyper-schema#",
"title": "Product",
"description": "A product available for sale in a store",
"type": "object",
"definitions": {
"identifier": {
"type": "string",
"description": "Product SKU",
"example": "ABC-123"
},
"name": {
"type": "string",
"description": "Product's name",
"maxLength": 100
},
"description": {
"type": "string",
"description": "Product's description",
"maxLength": 2000
}
},
"required": [
"id",
"name",
"description"
],
"properties": {
"id": {
"type": "string",
"description": "Product SKU",
"example": "ABC-123"
},
"name": {
"type": "string",
"description": "Product's name",
"maxLength": 100
},
"description": {
"type": "string",
"description": "Product's description",
"maxLength": 2000
}
},
"links": [
{
"title": "Available products",
"description": "Get all available product for the store",
"rel": "instances",
"href": "/products",
"method": "GET",
"schema": {
"type": "object",
"properties": {
"page": {
"type": "integer",
"description": "Current page of products",
"example": 1,
"default": 1
}
}
},
"targetSchema": {
"type": "array",
"items": {
"rel": "self"
}
}
},
{
"title": "Product info",
"description": "Get a single product",
"rel": "self",
"href": "/products/{#/definitions/identifier}",
"method": "GET",
"targetSchema": {
"rel": "self"
}
}
]
}
`json`
{
"id": "https://api.example.com/product",
"title": "Product",
"description": "A product available for sale in a store",
"type": "object",
"links": [
{
"title": "Available products",
"description": "Get all available product for the store",
"rel": "instances",
"href": "/products",
"method": "GET",
"html_id": "product-available-products",
"uri": "/products",
"curl": "curl -X GET \"/products?page=1\" \\\n",
"parameters": {
"_formatter": {},
"all_props": {
"page": {
"type": "integer",
"example": "1",
"description": "Current page of products",
"default": 1
}
},
"required_props": [],
"optional_props": [
"page"
],
"objects": [],
"example": "{\n \"page\": 1\n}"
},
"response": "{}"
},
{
"title": "Product info",
"description": "Get a single product",
"rel": "self",
"href": "/products/{#/definitions/identifier}",
"method": "GET",
"html_id": "product-product-info",
"uri": "/products/:identifier",
"curl": "curl -X GET \"/products/ABC-123\" \\\n",
"response": "{\n \"id\": \"ABC-123\"\n}"
}
],
"html_id": "product",
"object_definition": {
"_formatter": {},
"all_props": {
"id": {
"type": "string",
"example": "\"ABC-123\"",
"description": "Product SKU"
},
"name": {
"type": "string",
"description": "Product's name",
"maxLength": 100
},
"description": {
"type": "string",
"description": "Product's description",
"maxLength": 2000
}
},
"required_props": [
"id",
"name",
"description"
],
"optional_props": [],
"objects": [],
"example": "{\n \"id\": \"ABC-123\"\n}",
"title": "Product",
"description": "A product available for sale in a store"
}
}
As you can see, some properties are missing and some are added/updated. Removed properties are typically used in order to compute new properties and they are not needed anymore. Since we want to minimize the ouput as much as possible they are stripped. This happens on two levels:
- root - schema root
- links - array of links
At the root level:
- properties
- additionalProperties
- definitions
- allOf
- anyOf
- oneOf
- required
- $schema
At the link level:
- schema
- targetSchema
At the root level:
- html_id : string - URL friendly schema id
- object_definition : object
- all_props : object - all required properties (object where keys = prop names)
- required_props : array - list of keys in all_props
- optional_props : array - list of keys in all_props
- objects : array - nested object_definition (in case when oneOf/anyOf are used)
- which_of : string - the name of the property used for objects, if any
- example : string - stringified example of the whole schema object
At the link level:
- html_id : string - URL friendly schema + link id
- uri : string - link uri (resolved href)
- curl : string - curl example
- parameters : object
- all_props : object - all required properties (object where keys = prop names)
- required_props : array - list of keys in all_props
- optional_props : array - list of keys in all_props
- objects : array - nested parameters (in case when oneOf/anyOf/allOf are used)
- example : string - stringified example of request parameters
- response : string - response example, based on link/targetSchema
All custom properties that you add to the schema root or link object will be preserved. For example, you might want to set a flag "deprecated" to some of the links (endpoints) and write condition in your UI component.
Link Curl examples can be further customized (enriched) with baseUrl and optional request headers. This can be done through a query parameter that is accepted by this loader.
Notice: It includes json-schema-loader (use matching major version) in a chain.
`jsjson-schema-example?${JSON.stringify(config)}!json-schema
module: {
loaders: [{
test: /\.json$/,
loader: ,`
}],
},
Where config.curl.requestHeaders is a constant following JSON Schema format.
`js`
const config = {
curl: {
baseUrl: 'https://api.example.com/v1',
requestHeaders: {
required: [
'Content-Type',
'X-Auth-Email',
'X-Auth-Key',
],
properties: {
'X-Auth-Email': {
type: 'string',
description: 'Your email',
example: 'user@example.com',
},
'X-Auth-Key': {
type: 'string',
length: 45,
description: 'Your API key',
example: 'c3447eb745079oiu9320b638f5e225cf483cc5cfdda41',
},
'Content-Type': {
type: 'string',
enum: [
'application/json',
],
example: 'application/json',
description: 'Content type of the API request',
},
},
},
},
};
`js``
// ...
"links": [
{
"title": "Available products",
"description": "Get all available product for the store",
"rel": "instances",
"href": "/products",
"method": "GET",
"html_id": "product-available-products",
"uri": "/products",
"curl": "curl -X GET \"https://api.example.com/v1/products?page=1\" \\\n -H \"X-Auth-Email: user@example.com\" \\\n -H \"X-Auth-Key: c3447eb745079oiu9320b638f5e225cf483cc5cfdda41\" \\\n -H \"Content-Type: application/json\"",
"parameters": {
"_formatter": {},
"all_props": {
"page": {
"type": "integer",
"example": "1",
"description": "Current page of products",
"default": 1
}
},
"required_props": [],
"optional_props": [
"page"
],
"objects": [],
"example": "{\n \"page\": 1\n}"
},
"response": "{}"
},
{
"title": "Product info",
"description": "Get a single product",
"rel": "self",
"href": "/products/{#/definitions/identifier}",
"method": "GET",
"html_id": "product-product-info",
"uri": "/products/:identifier",
"curl": "curl -X GET \"https://api.example.com/v1/products/ABC-123\" \\\n -H \"X-Auth-Email: user@example.com\" \\\n -H \"X-Auth-Key: c3447eb745079oiu9320b638f5e225cf483cc5cfdda41\" \\\n -H \"Content-Type: application/json\"",
"response": "{\n \"id\": \"ABC-123\"\n}"
}
],
// ...