googleapis / googleapis/google-api-nodejs-client

Add & Export All API Enums

Offen
#2,866 0 Kommentare 1 Reaktion 0 zugewiesene Personen Auf GitHub ansehen
type: feature request
Vorherrschende Sprache
TypeScript
Sterne
12.2k
Forks
2k
Ø Merge
1 T. 9 Std.
Gemergte PRs (30 T.)
24

Beschreibung

Merry Christmas 🎄

**Describe the solution you'd like**

1. I would like **TypeScript enums** for all enum properties that are found within API discovery documents.
1. I would like any **method** that has a parameter containing both `"type": "string"` and `"enum": [...]` to have this enum type instead of a `string` type.

## ACTUAL

- There are no TypeScript enums in the client
- The enum types are just type `string`

Code example:

```ts
export interface Params$Resource$Presentations$Pages$Getthumbnail
extends StandardParameters {
/**
* The object ID of the page whose thumbnail to retrieve.
*/
pageObjectId?: string;
/**
* The ID of the presentation to retrieve.
*/
presentationId?: string;
/**
* The optional mime type of the thumbnail image. If you don't specify the mime type, the mime type defaults to PNG.
*/
'thumbnailProperties.mimeType'?: string;
/**
* The optional thumbnail image size. If you don't specify the size, the server chooses a default size of the image.
*/
'thumbnailProperties.thumbnailSize'?: string;
}
```

Link: https://github.com/googleapis/google-api-nodejs-client/blob/d3c557b4d5f5743f95ec7afd1e600b14985000a4/src/apis/slides/v1.ts#L3430

Notice how you must use a raw string parameter and do not have access to enums.

## EXPECTED

I expect enums to be exported as well:

```ts
// NEW
export enum Enum$Resource$Presentations$Pages$Getthumbnail$MimeType {
/**
* The default mime type.
*/
PNG = "PNG";
}
```

This would be used within the type:

```ts
export interface Params$Resource$Presentations$Pages$Getthumbnail
extends StandardParameters {
/**
* The object ID of the page whose thumbnail to retrieve.
*/
pageObjectId?: string;
// ...
/**
* The optional mime type of the thumbnail image. If you don't specify the mime type, the mime type defaults to PNG.
*/
'thumbnailProperties.mimeType'?: Enum$Resource$Presentations$Pages$Getthumbnail$MimeType;
/**
* The optional thumbnail image size. If you don't specify the size, the server chooses a default size of the image.
*/
'thumbnailProperties.thumbnailSize'?: Enum$Resource$Presentations$Pages$Getthumbnail$ThumbnailSize;
}
```

See the discovery document for a better idea of this:

https://slides.googleapis.com/$discovery/rest?version=v1

```json
"thumbnailProperties.mimeType": {
"enum": [
"PNG"
],
"enumDescriptions": [
"The default mime type."
],
"location": "query",
"type": "string",
"description": "The optional mime type of the thumbnail image. If you don't specify the mime type, the mime type defaults to PNG."
},
```

## ACTUAL: Real life usage (my case)

```ts
#slides: slides_v1.Slides;
// ...
const thumbnail = await this.#slides.presentations.pages.getThumbnail({
presentationId: presentationId,
pageObjectId: page.objectId + '',
// https://developers.google.com/slides/reference/rest/v1/presentations.pages/getThumbnail#thumbnailsize
'thumbnailProperties.thumbnailSize': 'MEDIUM',
});
```

Notice how you must use a raw string parameter and do not have access to enums.

## EXPECTED: Ideal usage

```ts
#slides: slides_v1.Slides;
// ...
const thumbnail = await this.#slides.presentations.pages.getThumbnail({
presentationId: presentationId,
pageObjectId: page.objectId + '',
// https://developers.google.com/slides/reference/rest/v1/presentations.pages/getThumbnail#thumbnailsize
thumbnailProperties: {
thumbnailSize: Enum$Resource$Presentations$Pages$Getthumbnail$MimeType.MEDIUM,
}
});
```

I suppose it would be okay to initially not add the better properties object (i.e. use `'thumbnailProperties.thumbnailSize'`):

```ts
#slides: slides_v1.Slides;
// ...
const thumbnail = await this.#slides.presentations.pages.getThumbnail({
presentationId: presentationId,
pageObjectId: page.objectId + '',
// https://developers.google.com/slides/reference/rest/v1/presentations.pages/getThumbnail#thumbnailsize
'thumbnailProperties.thumbnailSize': Enum$Resource$Presentations$Pages$Getthumbnail$MimeType.MEDIUM,
});
```

The type checker should also support just 'medium' here too instead of `Enum$Resource$Presentations$Pages$Getthumbnail$MimeType.MEDIUM`.

---

**Describe alternatives you've considered**

Right now developers use string literals for enums.

**Additional context**

Related: https://github.com/googleapis/google-api-nodejs-client/issues/2605

Beitragsleitfaden

Beitragsleitfaden öffnen

Rechercherichtung

Verwende das Slides-Discovery-Dokument und das generierte src/apis/slides/v1.ts-Beispiel als Ausgangspunkte. Verfolge, wie Discovery-Enum-Eigenschaften zu TypeScript-Parametertypen werden, und definiere dann die exportierten Enums und Substitutionen für alle übereinstimmenden String-Enum-Parameter; abgeschlossen ist die Aufgabe, wenn generierte Clients diese Enums bereitstellen und dabei die Kompatibilität mit String-Literalen erhalten bleibt.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Bewertung

Tech-Stack
typescript
Bereich
api, tooling
Issue-Typ
Feature
Schwierigkeit
5/5
Geschätzter Aufwand
Über eine Woche
Aktivitätsstatus
Veraltet
Klarheit
Größtenteils klar
Anfängerfreundlichkeit
35/100

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.