README

API schema

A library that generates schemas from the AMF model.

This is a work in progress.

Usage

Installation

npm install --save @api-client/api-schema

Generating schemas

The library takes an AMF shape as the argument, a media type of the generated schema as the other argument and generates schema depending what is defined in the model and the configuration.

Scalars processing:

If the shape is not required and renderOptional is not set return undefined.
If there's a default value, return the default value according to schema's data type
If there's an enum value, return the first enum value according to schema's data type
If there's an example and renderExamples is set then return parsed example value according to schema's data type
Otherwise return a value that is a "default" value for the given data type ('', 0, false, null).

Objects are processed property-by-property as defined above.

For unions you can pass the selectedUnions[] configuration option which the ids of all explicitly selected union members. When the library cannot find a member in the selectedUnions array then it takes the first available member to process the schema.

Union of a scalar and nil (or multiple scalars and nil) is treated like an optional property and it doesn't render values if renderOptional is not set.

import { ApiSchemaGenerator } from '@api-client/api-schema';

const shape = readAmfShapeSomehow()
const result = ApiSchemaGenerator.asSchema(shape, 'application/json', {
  renderOptional: true,
  renderExamples: true,
});
console.log(result);

Generating Monaco schemas

Currently only NodeShape is supported when generating a Monaco schema.

import { ApiMonacoSchemaGenerator } from '@api-client/api-schema';

const shape = readAmfShapeSomehow();
const reader = new ApiMonacoSchemaGenerator();
const result = reader.generate(shape, 'https://domain.com');
console.log(result);

Reading schema values for form inputs

This class reads a value that should be rendered in a form input for the generated schema. Note, there are two methods to read scalar and array values. Also, this class operates on Parameters rather than Shapes.

import { ApiSchemaValues } from '@api-client/api-schema';

const parameter = readAmfParameterSomehow();
const result = ApiSchemaValues.readInputValue(parameter);
console.log(result); // string, number, boolean, null, undefined, object, array

const arrayResult = ApiSchemaValues.readInputValues(parameter);
console.log(arrayResult); // list of: string, number, boolean, null, undefined, object, array

const inputType = ApiSchemaValues.readInputType('http://a.ml/vocabularies/shapes#number');
console.log(inputType); // "number"

const parsedValue = ApiSchemaValues.parseScalarInput('25', numberScalarShape);
console.log(parsedValue); // 25

Reading example values from examples

This class specializes in reading and processing AMF examples to a form that should be rendered to the user as an example value of a scheme or a property.

Note, that you need to provide a media type for which generate the value for. Currently the following media types are supported:

application/json
application/xml
application/x-www-form-urlencoded

import { ApiExampleGenerator } from '@api-client/api-schema';
const reader = new ApiExampleGenerator();
const shape = readAmfShapeSomehow();
const result = reader.read(shape.examples[0], 'application/json');
console.log(result); // a string representing a JSON value.

Note, when the example comes from a scalar shape the returned value is this scalar value which is not a valid JSON.

Development

git clone https://github.com/@api-client/api-schema
cd api-schema
npm install

Running the demo locally

npm start

Running the tests

npm test

License

API Components by Pawel Psztyc is licensed under CC BY 4.0

Usage no npm install needed!