https://github.com/sashafklein/ts-api
https://github.com/sashafklein/ts-api
Last synced: 2 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/sashafklein/ts-api
- Owner: sashafklein
- Created: 2022-05-11T05:33:56.000Z (about 3 years ago)
- Default Branch: master
- Last Pushed: 2022-05-22T17:16:25.000Z (about 3 years ago)
- Last Synced: 2025-02-09T06:41:17.876Z (4 months ago)
- Language: TypeScript
- Size: 427 KB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# TypeScript OpenAPI
This repo is a proof-of-concept of a TypeScript-augmented OpenAPI schema repository.
A number of pieces of type-checked functionality are available for more easily constructing valid OpenAPI specs, and a `compile` script has been added to bundle the TS into JSON, build the JSON into HTML, and generate types from the bundle.
## Compiling
```bash
npm run compile
```
## Added Functionality
### Extended Schemas
The `Schema` functionality allows you to define broad schemas containing every relevant field for a domain object, and then pick and choose which fields you want, and which are required, on a per-use basis:
```ts
import { field2, field3, field4 } from '@myservice/fields';
export const Example = Schema('ExampleSchema', {
someField: {
type: 'string',
example: 'hello'
}
field2,
field3,
field4
});
// ...
// Returns just the requested properties, with the right ones required
Example().pick('field2', 'field3', 'field4').require('field3').toSpec()
// Results in the same as the above
Example().omit('someField').require('field3').toSpec()
```
> Note that type checking would catch an improper field in the above (eg, one without a valid `type`).
### Yaml Fields
It's easy to accept YAML for field or simple schema definitions. All the pre-defined fields currently in this repo are YAML.
### Type Checking
If, for example, an invalid field were added above, it would raise an error:
```ts
export const Example = Schema('ExampleSchema', {
// Missing a required `type`
someField: {
example: 'hello'
}
field2,
field3,
field4
});
```
It will even detect more subtle errors:
```ts
export const Example = Schema('ExampleSchema', {
// Mismatched `type`
someField: {
type: 'integer',
example: 'hello'
}
field2,
field3,
field4
});
```
Error:
```
Types of property 'example' are incompatible.
Type 'string' is not assignable to type 'number'.
```
### Example Generation
For any endpoint made with the `makeEndpoint` function, a `default` example will be autogenerated based on types.
In the future, we could make it easy to generate additional examples with single fields/sections altered.
### Best Practices
If, for example, we want a single endpoint tag, or each endpoint summary to be a camelcased function call identical to the operationId (eg `getPerson`) that is easy to build into the type validations. Similarly, we could enforce an example for each field, etc.