Skip to content

Latest commit

 

History

History
235 lines (155 loc) · 10.2 KB

README.md

File metadata and controls

235 lines (155 loc) · 10.2 KB
Raw

google-api-typings-generator

GitHub Code Style: Google Dependabot Status Donate

Auto Publish to NPM Auto Generate Types CI Test

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:

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:

    • all discovered Google APIs:

      npm start

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

    • 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 or here.

    • one service by URL:

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

      Note that we have to use ＄ - full-width dollar sign instead of the regular $, it will be replaced by the script, this is to avoid complications with 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.

Syncing gapi client namespace in DT with available APIs

Here's how to sync (add new and remove obsolete) Google APIs to/from @types/gapi.client.* namespace in DefinitelyTyped:

  1. Make sure that this project, DefinitelyTyped/DefinitelyTyped, and microsoft/DefinitelyTyped-tools are all in the home directory on Linux: ~
  2. Ensure that both DT and DT-tools are reset to latest master
  3. npm run apis-sync-helper will update allowed list in DT-tools (only adds new packages and removes ones that are no longer in DT)
  4. npm run start-dt will update DT
  5. Open PR to DT-tools
  6. Wait for it to get merged
  7. Open PR to DT
  8. Once it's merged - all done, rinse and repeat in a few months or so.

Ideally, this should be automated in #401

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 Vitest. 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 many human resources of DT.

See Syncing gapi client namespace in DT with available APIs section for instructions.

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 the first one seems to be the 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 the request body. In that case, we only generate the 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 the client-side (in the browser) and on the server-side.

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

The 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