# HATCH_CLI_TEMPLATE_VAR_projectShortName
This project is a TypeScript API project that defines or generates an 
[OpenAPI Specification](https://swagger.io/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](https://github.com/airtasker/spot/wiki/Spot-Syntax) to define an OpenAPI
specification. Spot uses a
[TypeScript-based DSL](https://github.com/airtasker/spot/wiki/Spot-Syntax) 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. `--spec-to-deference` can alternatively be used if your input spec has external
references that need to first be resolved before it is merged with other specs.

### 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.