google-api-typings-generator

Generate TypeScript type definitions for all Google APIs, using Google API discovery service.

Meant to be used with Google APIs JavaScript Browser Client, aka gapi. Not to be mistaken with NodeJS Server Client which is already in TS; details

Fork Log:

• ⚠️ This is the only maintained repo for GAPI type definitions (forked and detached from Bolisov/google-api-typings-generator)
• 🤖 Auto updates every hour; details
• Supports both resource and second-argument approaches; details
• Includes empty interfaces; details
• Works for arrays, aka "repeated": true; details
• System proxy support (see Azure/get-proxy-settings)
• Other minor fixes and updates

Usage

Generating types

1. Use the supported Node version via Node Version Manager:

   nvm install

2. Install dependencies:

   npm install

3. Generate type definitions for:

   1. all discovered Google APIs:

      npm start

      Some APIs are disabled or not fully developed yet, so some expected errors might be output.

   2. one service by name:

      npm start -- --service sheets

      where sheets is the name of the Google Sheets service.

      The full list of APIs can be found here.

   3. one service by URL:

      npm start -- --url https://sheets.googleapis.com/\\\$discovery/rest?version=v4

      Note the intentional escaping of $discovery.

Compiling project

npm run compile

node dist/cli.js --out ./types

Running tests

Tests are run automatically in practice via GitHub Actions continuous integration.

Lint

The generated type definitions are linted via dtslint, mimicking DefinitelyTyped's process.

A single project can be linted via:

npm run dtslint types/<project-directory>

All projects can be linted in parallel via:

GAPI_MAX_PARALLEL=3 npm run lint

Unit (WIP)

Unit tests for this generator project are written with Jasmine and Mocha. They can be run via:

npm run test

Fixing formatting

This project leverages Google's TypeScript Style (gts) to standardize formatting.

To invoke the automatic code fixer, run:

npm run fix

Publishing to DefinitelyTypes @types

Do not publish types to DT directly

We've switched to publishing "real" types to npm as @maxim_mazurok/gapi.client.* and then referencing them in @types/gapi.client.* so that we can release updates automatically and quickly, without using too much human resources of DT.

1. Run this script:

   npx ts-node ./src/dt/cli.ts -o ~/DefinitelyTyped/types

   , where ~/DefinitelyTyped is the path to your local clone of DT repo

2. Commit to your branch, push to your fork and open PR

Details

Auto Updates

Every hour, type definitions are generated, linted, tested and published to NPM.

Resource VS Body

First approach (Resource):

gapi.client.sheets.spreadsheets.batchUpdate({
  spreadsheetId: 'someId',
  resource: {
    // Request Body goes here, as part of `request`
  },
});

second approach (Body):

gapi.client.sheets.spreadsheets.batchUpdate(
  {
    spreadsheetId: 'someId',
  },
  {
    // Request Body goes here, as a second argument
  }
);

Both approaches are valid (tested for Google Sheets API), but first one seems to be default for JS Client Library.

More info here: google/google-api-javascript-client#432 (comment), and here: declanvong@bec4f89#r35992626

NOTE: Some APIs have methods that accept resource parameter that is not request body. In that case, we only generate second approach (details)

Empty interfaces

This fork keeps interfaces even if they are empty to make typings more accurate.

More info here: Maxim-Mazurok/google-api-typings-generator#4

Arrays / repeated values

This fork understands "repeated": true

More info here: Maxim-Mazurok/google-api-typings-generator#1 and here: declanvong@bec4f89#r35992626

JavaScript VS NodeJS Clients

There are two ways to use Google APIs: on client-side (in browser) and on server-side.

Client-side library, called gapi is kinda closed-source. We can see compiled (unreadable minified) JS code of the client-side library. When you use any Google JS API, you use gapi. It loads library definitions from Google API Discovery Service and generates all API calls on the fly.

So, there's no TS version of gapi because it's closed-source and other client libraries do not exist, because they are being generated on the fly by gapi.

If you want to use TypeScript with gapi - you have to use type definitions generated by this project. While we do generate typings for Google APIs, we can't generate gapi typings from discovery, so we rely on @types/gapi and you also should.

Server-side libraries are open-sourced and are available here. Since they are written in TS, you don't need any additional type definitions to use them.

Troubleshooting

npm install - 404 Not Found

The error looks like this (see #483):

$ npm install @types/gapi.client.YOUR_API@v2 --save-dev
npm ERR! code E404
npm ERR! 404 Not Found - GET https://registry.npmjs.org/@types%2fgapi.client.YOUR_API - Not found
npm ERR! 404
npm ERR! 404  '@types/gapi.client.YOUR_API@v2' is not in the npm registry.
npm ERR! 404 You should bug the author to publish it (or use the name yourself!)

It's most likely caused by your API package not being published to NPM yet.

To fix this - open an issue and I'll update the list of supported APIs.

Later on, when #401 is closed - this process will be automated.

Also, you can use these types from the types branch