hatch-scim2-api

This project is a TypeScript API project that defines or generates an OpenAPI Specification.

API projects such as this one are typically used as inputs to an auto-generated client and/or server SDK project, which are in turn often used by webapp projects to define and interact with HTTP-based APIs in a type-safe, consistent way.

Defining an OpenAPI specification using JSON or YAML directly can be cumbersome and error-prone. This project is meant to encapsulate the definition of an API, using tools to cut down on cumbersome boilerplate and assist with merging together multiple type and API definitions.

Specification formats

There are multiple formats that this project can use for defining an OpenAPI specification.

Spot

Optionally (and by default), this project can use a Spot file to define an OpenAPI specification. Spot uses a TypeScript-based DSL to define APIs with minimal boilerplate. Spot APIs can be generated by adding --spot [input-spot-file] to the build scripts in package.json.

YAML (or JSON)

This project can use raw YAML or JSON OpenAPI specification files as inputs. Note that since JSON or YAML APIs can be generated by adding --spec [input-spec-file]to the build scripts in package.json.

Combining formats

Multiple specification formats can be used in this project. The generator will merge outputs together as necessary. This is governed by the ordering of hatch-api arguments in the build and build:watch scripts in package.json. In the case of merge conflicts, the first argument precedence. For example, this command will allow definitions in api-overrides.yaml to override definitions in the api.ts Spot file:

hatch-api --spec src/api-overrides.yaml --spot src/api.ts

The above is the default used by this project: a Spot specification that can be overridden by a raw YAML OpenAPI specification.