isl-types-integration

TypeScript type definitions and JSON schemas for integration APIs based on the OpenAPI definition, which is also maintained in this repository.

Installation

First, make sure you are logged-in to the private NPM registry:

$ npm adduser --registry=https://registry.npmjs.org/ --scope=@aptos-scp

Then install the dependency packages:

$ npm install @aptos-scp/isl-types-integration

##Usage

Building

This package contains only schemas and interface definitions, so there isn't code to compile. To generate the interfaces and bundle the OpenAPI definition and JSON schemas from the source schema files, run this command:

$ npm run build

This will create the bundled OpenAPI definition and TypeScript definition files in the dist directory. The schemas subdirectory will have a bundled JSON schema for each type defined in the source schemas.

Visualizing the OpenAPI Definition

You can load the bundled definition into the Swagger Editor. There's also a npm script that will start a local server to host the definition and open your browser to view it:

$ npm run serve:openapi

TypeScript Interfaces

The TypeScript interfaces can be imported and used anywhere to ensure consistent type checking across clients and any service that implements this integration API.

JSON Schemas

A JSON schema for each type is installed with the package in dist/schemas. You may use the schemas to perform data validation.

OpenAPI Definition

The OpenAPI definition is installed with the package in dist/integration.openapi.yaml. You may use the definition as a reference and to auto-generate a client implementation that interacts with the service. The definition can be used by a service to auto-generate Hapi routes and to perform request and response validation.

Making Changes

The TypeScript interfaces are auto-generated from the schemas in the schemas directory. We have adopted a standard practice to keep request and response schemas separate from the OpenAPI definition file. See the existing examples for how those should be formatted and referenced.

The way we generate TypeScript interfaces involves flattening all schema definitions into one list. Keep this in mind when naming definition, since two definitions with the same name will cause a name conflict even if in separate files.

When you've made a change to the definition or one of the schemas, you can validate and lint your changes:

$ npm run lint:openapi

Be sure to run a build before committing your code to ensure your schemas can be bundled and TypeScript interfaces automatically generated.

License

Please see LICENSE.md.