README.md

orval

Inspired by restful-react

• Code Generation
  • Usage
  • Validation of the OpenAPI specification
  • Import from GitHub
  • Transforming an Original Spec
  • Advanced configuration
    • Config File Format
    • Config File Example

Code Generation

orval 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:

• orval import --file MY_OPENAPI_SPEC.yaml --output my-awesome-generated-types.tsx

This command can be invoked by either:

• Installing orval globally and running it in the terminal: npm i -g orval, or
• Adding a script to your package.json like so:

      "scripts": {
        "start": "webpack-dev-server",
        "build": "webpack -p",
+       "generate-fetcher": "orval 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": "orval 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 orval call.

Import from GitHub

Adding the --github flag to orval 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:

1. Visit your GitHub settings.

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

3. Click Generate token.

4. Copy the generated string.

5. Open a terminal and run orval import --github username:repo:branch:path/to/openapi.yaml --output MY_FETCHERS.tsx, substituting things where necessary.

6. You will be prompted for a token.

7. Paste your token.

8. 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 each npm install of orval.

9. 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:

  orval 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 orval's generator. Here's how it can be used:

// /path/to/my-transformer.js

/**
 * Transformer function for orval.
 *
 * @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

orval 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, orval.config.js

To activate this "advanced mode", replace all flags from your orval call with the config flag: --config orval.config.js (or any filename that you want).

⚠️ Note: using a config file makes use of all of the options contained therein, and ignores all other CLI flags.

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

// orval.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": "orval import --config orval.config.js",
    "gen-first": "orval import --config orval.config.js myFirstBackend"
  }
}