@api-client/api-schema v0.1.1
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