googleapis / googleapis/google-api-nodejs-client

Add & Export All API Enums

Aperta
#2,866 0 commenti 1 reazione 0 assegnatari Vedi su GitHub
type: feature request
Lingua principale
TypeScript
Stelle
12.3k
Fork
2k
Merge medio
1g 9h
PR unite (30g)
24

Descrizione

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

Guida per i contributori

Apri la guida per i contributori

Direzione di ricerca

Usa il documento di discovery di Slides e l'esempio generato src/apis/slides/v1.ts come punti di partenza. Traccia come le proprietà enum della discovery diventano tipi di parametro TypeScript, quindi definisci gli enum esportati e le sostituzioni per tutti i parametri string-enum corrispondenti; il lavoro è completato quando i client generati espongono tali enum preservando al contempo la compatibilità con i valori letterali stringa.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Valutazione

Stack tecnologico
typescript
Ambito
api, tooling
Tipo di issue
Funzionalità
Difficoltà
5/5
Tempo stimato
Più di una settimana
Stato di attività
Ferma
Chiarezza
Abbastanza chiara
Idoneità per principianti
35/100

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.