restful-client
Inspired by restful-react
Code Generation
restful-client
is able to generate axios client with appropriate type-signatures (TypeScript) from any valid OpenAPI v3 or Swagger v2 specification, either in yaml
or json
formats.
Usage
Type-safe data fetchers can be generated from an OpenAPI specification using the following command:
restful-client import --file MY_OPENAPI_SPEC.yaml --output my-awesome-generated-types.tsx
This command can be invoked by either:
- Installing
restful-client
globally and running it in the terminal:npm i -g restful-client
, or - Adding a
script
to yourpackage.json
like so:
"scripts": {
"start": "webpack-dev-server",
"build": "webpack -p",
+ "generate-fetcher": "restful-client import --file MY_SWAGGER_DOCS.json --output FETCHERS.tsx"
}
Your client can then be generated by running npm run generate-fetcher
. Optionally, we recommend linting/prettifying the output for readability like so:
"scripts": {
"start": "webpack-dev-server",
"build": "webpack -p",
"generate-fetcher": "restful-client import --file MY_SWAGGER_DOCS.json --output FETCHERS.tsx",
+ "postgenerate-fetcher": "prettier FETCHERS.d.tsx --write"
}
Validation of the OpenAPI specification
To enforce the best quality as possible of specification, we have integrated the amazing OpenAPI linter from IBM. We strongly encourage you to setup your custom rules with a .validaterc
file, you can find all useful information about this configuration here.
To activate this, add a --validation
flag to your restful-client
call.
Import from GitHub
Adding the --github
flag to restful-client import
instead of using the --file
flag allows us to create your client from an OpenAPI spec remotely hosted on GitHub. (how is this real life
To generate components from remote specifications, you'll need to follow the following steps:
-
Visit your GitHub settings.
-
Click Generate New Token and choose the following:
Token Description: (enter anything) Scopes: [X] repo [X] repo:status [X] repo_deployment [X] public_repo [X] repo:invite
-
Click Generate token.
-
Copy the generated string.
-
Open a terminal and run
restful-client import --github username:repo:branch:path/to/openapi.yaml --output MY_FETCHERS.tsx
, substituting things where necessary. -
You will be prompted for a token.
-
Paste your token.
-
You will be asked if you'd like to save it for later. This is entirely up to you and completely safe: it is saved in your
node_modules
folder and not committed to version control or sent to us or anything: the source code of this whole thing is public so you're safe.Caveat: Since your token is stored in
node_modules
, your token will be removed on eachnpm install
ofrestful-client
. -
You're done!
🎉
Transforming an Original Spec
In some cases, you might need to augment an existing OpenAPI specification on the fly, for code-generation purposes. Our CLI makes this quite straightforward:
restful-client import --file myspec.yaml --output mybettercomponents.tsx --transformer path/to/my-transformer.js
The function specified in --transformer
is pure: it imports your --file
, transforms it, and passes the augmented OpenAPI specification to restful-client
's generator. Here's how it can be used:
// /path/to/my-transformer.js
/**
* Transformer function for restful-client.
*
* @param {OpenAPIObject} schema
* @return {OpenAPIObject}
*/
module.exports = inputSchema => ({
...inputSchema,
// Place your augmentations here
paths: Object.entries(schema.paths).reduce(
(mem, [path, pathItem]) => ({
...mem,
[path]: Object.entries(pathItem).reduce(
(pathItemMem, [verb, operation]) => ({
...pathItemMem,
[verb]: {
...fixOperationId(path, verb, operation),
},
}),
{},
),
}),
{},
),
});
Advanced configuration
restful-client
supports the concept of "schema stitching" in a RESTful ecosystem as well. We are able to tie multiple backends together and generate code using a single configuration file, restful-client.config.js
To activate this "advanced mode", replace all flags from your restful-client
call with the config flag: --config restful-client.config.js
(or any filename that you want).
Config File Format
interface RestfulClientConfig {
[backend: string]: {
// classic configuration
output: string;
file?: string;
types?: string;
github?: string;
transformer?: string;
validation?: boolean;
mock?: boolean;
};
}
Config File Example
// restful-client.config.js
module.exports = {
'petstore-file': {
file: 'examples/petstore.yaml',
output: 'examples/petstoreFromFileSpecWithConfig.tsx',
types: './model',
mock: true,
},
'petstore-file-transfomer': {
file: 'examples/petstore.yaml',
output: 'examples/petstoreFromFileSpecWithTransformer.tsx',
types: './model',
transformer: 'examples/transformer-add-version.js',
mock: {
properties: {
id: 'faker.random.number({ min: 1, max: 9999 })',
},
responses: {
listPets: {
properties: () => {
return {
id: 'faker.random.number({ min: 1, max: 9 })',
};
},
},
showPetById: {
data: () => ({
id: faker.random.number({ min: 1, max: 99 }),
name: faker.name.firstName(),
tag: faker.helpers.randomize([faker.random.word(), undefined]),
}),
},
},
},
},
};
// package.json
{
"scripts": {
"gen": "restful-client import --config restful-client.config.js",
"gen-first": "restful-client import --config restful-client.config.js myFirstBackend"
}
}