genum-openapi

gEnum OpenAPI

About

genum-openapi is a simple Node.js CLI tool for creating TypeScript enums from OpenAPI document. This package is inspired by another tool named 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:

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

Then you can import the enums from the generated file:

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:

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}"

• By providing [--exclude Status InvalidCase StartWithNumber WithCurlyBrackets] option, generated file should contain only ColorsEnum:

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

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

export enum IStatus {
  [...]
}

export enum IColorsEnum {
  [...]
}

export enum IInvalidCase {
  [...]
}

export enum IStartWithNumber {
  [...]
}

export enum IWithCurlyBrackets {
  [...]
}

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

export enum StatusEnum {
  [...]
}

export enum ColorsEnum {
  [...]
}

export enum InvalidCaseEnum {
  [...]
}

export enum StartWithNumberEnum {
  [...]
}

export enum WithCurlyBracketsEnum {
  [...]
}

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

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

• 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):

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

• 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 "".

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

:mega: Goals

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

:couple_with_heart: Contributing

PRs are welcome!