# genum-openapi

> Generate Typescript enums from openapi

Latest version **0.8.0-alpha.2** (published 2024-07-05) · MIT license · 0 weekly downloads

## Install

```sh
npm install genum-openapi
pnpm add genum-openapi
yarn add genum-openapi
bun add genum-openapi
```

Provides the command `genum-openapi`.

## Health

**Score 20/100 (F)** — status: abandoned.

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.8.0-alpha.2 |
| Published | 2024-07-05 |
| First published | 2023-06-28 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Node | >=18.0.0 |
| Dependencies | 4 |
| Unpacked size | 20 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | mrdannael |
| Maintainers | mrdannael |
| Keywords | cli, openapi, typescript, nodejs, enum |

## Links

- npm: https://www.npmjs.com/package/genum-openapi
- Repository: https://github.com/mrdannael/genum-openapi
- Homepage: https://github.com/mrdannael/genum-openapi/blob/master/README.md
- npm.io page: https://npm.io/package/genum-openapi

## Dependencies (4)

- [yaml](https://npm.io/package/yaml.md) ^2.4.5
- [chalk](https://npm.io/package/chalk.md) ^5.3.0
- [commander](https://npm.io/package/commander.md) ^12.1.0
- [openapi-types](https://npm.io/package/openapi-types.md) ^12.1.3

## Alternatives

- [@salesforce/cli](https://npm.io/package/@salesforce/cli.md) — 389.7K weekly downloads
- [@mintlify/cli](https://npm.io/package/@mintlify/cli.md) — 208.9K weekly downloads
- [@grafana/e2e-selectors](https://npm.io/package/@grafana/e2e-selectors.md) — 128.7K weekly downloads
- [mintlify](https://npm.io/package/mintlify.md) — 112.0K weekly downloads
- [@intlayer/cli](https://npm.io/package/@intlayer/cli.md) — 22.8K weekly downloads

## Recent versions

- 0.8.0-alpha.2 (latest) — 2024-07-05
- 0.8.0-alpha.1 — 2024-07-02
- 0.8.0-alpha.0 — 2024-06-16
- 0.7.0 — 2024-06-14
- 0.6.0 — 2024-05-17
- 0.5.0 — 2024-01-12
- 0.4.0 — 2023-07-24
- 0.3.1 — 2023-07-15
- 0.3.0 — 2023-07-14
- 0.2.0 — 2023-06-29
- 0.1.6 — 2023-06-29
- 0.1.5 — 2023-06-29
- 0.1.3 — 2023-06-29
- 0.1.4 — 2023-06-29
- 0.1.2 — 2023-06-29
- … 2 more at https://npm.io/package/genum-openapi/versions

## README

# gEnum OpenAPI

![ci](https://github.com/mrdannael/genum-openapi/actions/workflows/nodejs.yaml/badge.svg)
![npm](https://img.shields.io/npm/v/genum-openapi)
![npm](https://img.shields.io/npm/dm/genum-openapi)

#

[![Tech used](https://skillicons.dev/icons?i=nodejs,ts)](https://skillicons.dev/)

## About

**genum-openapi** is a simple Node.js CLI tool for creating TypeScript enums from [OpenAPI](https://spec.openapis.org/oas/latest.html) document. This package is inspired by another tool named [openapi-typescript](https://github.com/drwpow/openapi-typescript/blob/main/packages/openapi-typescript). Toghether with mentioned package, developers should be able to generate TypeScript interfaces (using openapi-typescript) and enums (using genum-openapi) within their projects with the same YAML file as an input.

**Features**

- Supports OpenAPI 3.x
- Generate **TypeScript enums**
- Load schemas from local YAML or JSON file
- Native Node.js code used to write this tool

## Usage

Generate local file with Typescript enums by running `npx genum-openapi`:

```bash
npx genum-openapi ./path/to/the/schema.yaml -o ./path/to/generated/enums.ts
```

:warning: Make sure that all your schemas are validated before using them with [this](https://redocly.com/docs/cli/commands/lint/) tool.

Then you can import the enums from the generated file:

```ts
import { StatusEnum } from "./path/to/generated/enums";

export const App = () => {
  if (status === StatusEnum.SUCCESS) {
    console.log("Enum successfully generated and used");
  } else {
    console.log("Enum failed to generate");
  }
};
```

### :gear: Options

Following flags are available for the CLI tool.

| Option               | Alias | Default  | Description                                                                                                                |
| :------------------- | :---- | :------: | :------------------------------------------------------------------------------------------------------------------------- |
| `--help`             | `-h`  |          | Display help for the command                                                                                               |
| `--version`          | `-v`  |          | Output the current version                                                                                                 |
| `--output`           | `-o`  | (stdout) | Path of the output file                                                                                                    |
| `--exclude`          | `-e`  |          | Names of enums from the OpenAPI document to exclude                                                                        |
| `--prefix`           | `-p`  |          | Add a prefix to the beginning of the enum name                                                                             |
| `--suffix`           | `-s`  |   Enum   | Add a suffix to the end of the enum name if it does not already exist                                                      |
| `--prenum`           |       |    \_    | Add a specified prefix before the enum exported name that starts with a number (underscore by default if not provided)     |
| `--normalize`        | `-n`  |  false   | Normalize exported enum names and keys that are not valid (replace `.` with `__` and `-` or `/` with `_`)                  |
| `--normalize-keys`   |       |  false   | Normalize only enum keys that are not valid                                                                                |
| `--normalize-names`  |       |  false   | Normalize only exported enum names that are not valid                                                                      |
| `--uppercase`        | `-u`  |  false   | Convert exported enum names and keys to uppercase (commonly used with the `--normalize` option)                            |
| `--uppercase-keys`   |       |  false   | Convert only enum keys to uppercase                                                                                        |
| `--uppercase-names`  |       |  false   | Convert only exported enum names to uppercase                                                                              |
| `--custom-replacers` |       |          | Custom replacers applied during the normalization process, in JSON format, e.g., `'[{"regExp":"[-/]","replaceWith":"_"}]'` |

### :book: Examples

Let's say that our OpenAPI document looks like this:

```yaml
openapi: 3.0.3
info:
  title: Example OpenApi description
  version: 0.0.0
components:
  schemas:
    Status:
      enum:
        - ACTIVE
        - INACTIVE
      type: string
    ColorsEnum:
      enum:
        - GREEN
        - RED
      type: string
    InvalidCase:
      enum:
        - SOME/WEIRD-Strings
        - another.weird.string
        - just(another)weird string
      type: string
    StartWithNumber:
      enum:
        - 250x330
        - 70x40
        - OTHER
      type: string
    WithCurlyBrackets:
      enum:
        - "{INSIDE_CURLY_BRACKETS}"
```

1. By providing [`--exclude Status InvalidCase StartWithNumber WithCurlyBrackets`] option, generated file should contain only _ColorsEnum_:

```ts
export enum ColorsEnum {
  GREEN = "GREEN",
  RED = "RED",
}
```

2. [`--prefix I`] option should add provided string at the beggining of the enums names:

```ts
export enum IStatus {
  [...]
}

export enum IColorsEnum {
  [...]
}

export enum IInvalidCase {
  [...]
}

export enum IStartWithNumber {
  [...]
}

export enum IWithCurlyBrackets {
  [...]
}
```

3. [`--suffix`] option should add provided string at the end of the enums names (when not provided `Enum` is used by default):

```ts
export enum StatusEnum {
  [...]
}

export enum ColorsEnum {
  [...]
}

export enum InvalidCaseEnum {
  [...]
}

export enum StartWithNumberEnum {
  [...]
}

export enum WithCurlyBracketsEnum {
  [...]
}
```

4. With [`--normalize`] and [`--uppercase`] options, generated file should contain parsed values of enum keys:

```ts
[...]
export enum INVALIDCASE {
  SOME_WEIRD_STRINGS = "SOME/WEIRD-Strings",
  ANOTHER__WEIRD__STRING = "another.weird.string"
  JUST_ANOTHER_WEIRD_STRING = "just(another)weird string"
}
[...]
```

5. With [`--prenum $`] option, keys of enums should be prefixed with a `$` sign (by default enum keys that starts with a number are prefixed with an underscore):

```ts
[...]
export enum StartWithNumber {
  $250x330 = "250x330",
  $70x40 = "70x40",
  OTHER = "OTHER"
}
[...]
```

6. You can pass custom replacers to the cli with [`--custom-replacers '[{ "regExp":"[{}]", "replaceWith": "empty" }]'`] to replace any strings as you like. Keep in mind that in the provided example we want to replace `{}` with `""`, but due to `JSON.parse` used as the parsing method, we cannot simply pass `""` as a `replaceWith` property, instead we pass `"empty"` to handle replacing `{}` with `""`.

```ts
[...]
export enum WithCurlyBrackets {
  INSIDE_CURLY_BRACKETS = "{INSIDE_CURLY_BRACKETS}"
}
[...]
```

## :mega: Goals

1. Fetching schema from remote resource (with Auth header if needed)
2. Parsing multiple schemas at once (with globbing)

## :couple_with_heart: Contributing

PRs are welcome!

---
_Source: https://npm.io/package/genum-openapi · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._