@zenclabs/api
A TypeScript-based DSL to generate API contracts (OpenAPI, Swagger, JSON Schema, API Blueprint), client SDKs (TypeScript, Swift, Kotlin) or even server boilerplate (e.g. Express).
Example of an API definition file api.ts
which defines a single POST
endpoint to create a user:
import { api, endpoint, request } from "@zenclabs/api";
@api()
class Api {
@endpoint({
method: "POST",
path: "/users"
})
createUser(@request req: CreateUserRequest): CreateUserResponse {
throw "contract";
}
}
interface CreateUserRequest {
firstName: string;
lastName: string;
}
interface CreateUserResponse {
success: boolean;
}
You can pass the definition above to a generator by simply running:
npx @zenclabs/api generate --api api.ts
This is work in progress as of 3 Nov 2018:
- [x] Functional TypeScript DSL
- [x] Support for multiple files (using import statements)
- [x] OpenAPI 3 generator
- [x] OpenAPI 2 generator
- [x] JSON Schema generator
- [ ] API Blueprint generator
- [x] TypeScript axios-based client generator
- [x] TypeScript express-based server boilerplate generator
- [ ] Swift client generator
- [ ] Kotlin client generator
Usage
To get started and set up an API declaration in the current directory, run:
npx @zenclabs/api init
You can then run a generator with:
npx @zenclabs/api generate --api api.ts
Commands
api generate
Runs a generator on an API. Used to produce client libraries, server boilerplates and well-known API contract formats such as OpenAPI.
USAGE
$ api generate
OPTIONS
-a, --api=api (required) Path to a TypeScript API definition
-g, --generator=generator Generator to run
-h, --help show CLI help
-l, --language=language Language to generate
-o, --out=out Directory in which to output generated files
EXAMPLE
$ api generate --language typescript --generator axios-client --out src/
Generated the following files:
- src/types.ts
- src/validators.ts
- src/client.ts
See code: build/cli/src/commands/generate.js
api help [COMMAND]
display help for api
USAGE
$ api help [COMMAND]
ARGUMENTS
COMMAND command to show help for
OPTIONS
--all see all commands in CLI
See code: @oclif/plugin-help
api init
Generates the boilerplate for an API.
USAGE
$ api init
OPTIONS
-h, --help show CLI help
EXAMPLE
$ api init
Generated the following files:
- api.ts
- tsconfig.json
- package.json
See code: build/cli/src/commands/init.js