# @eriklenaerts/openapi-docgen

> Generate an Open API document to kick start your REST API design or development.

Latest version **0.5.0** (published 2025-10-29) · MIT license · 0 weekly downloads

## Install

```sh
npm install @eriklenaerts/openapi-docgen
pnpm add @eriklenaerts/openapi-docgen
yarn add @eriklenaerts/openapi-docgen
bun add @eriklenaerts/openapi-docgen
```

Provides the commands `oadc`, `openapi-docgen`.

## Health

**Score 50/100 (C)** — status: stable.

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.5.0 |
| Published | 2025-10-29 |
| First published | 2021-07-31 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Node | >=24.0.0 |
| Dependencies | 11 |
| Unpacked size | 107.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Erik Lenaerts |
| Maintainers | eriklenaerts |
| Keywords | cli, openapi-docgen, generator, oas, openapi, swagger |

## Links

- npm: https://www.npmjs.com/package/@eriklenaerts/openapi-docgen
- npm.io page: https://npm.io/package/@eriklenaerts/openapi-docgen

## Dependencies (11)

- [arg](https://npm.io/package/arg.md) ^5.0.0
- [axios](https://npm.io/package/axios.md) >=0.21.2
- [chalk](https://npm.io/package/chalk.md) ^5.6.2
- [dotenv](https://npm.io/package/dotenv.md) ^17.2.3
- [nanoid](https://npm.io/package/nanoid.md) ^5.1.6
- [inquirer](https://npm.io/package/inquirer.md) ^12.10.0
- [pluralize](https://npm.io/package/pluralize.md) ^8.0.0
- [set-value](https://npm.io/package/set-value.md) >=4.0.1
- [handlebars](https://npm.io/package/handlebars.md) ^4.7.7
- [highlight.js](https://npm.io/package/highlight.js.md) >=10.4.1
- [handlebars-helpers](https://npm.io/package/handlebars-helpers.md) ^0.10.0

## Alternatives

- [update-check](https://npm.io/package/update-check.md) — 4.0M weekly downloads
- [react-native-onesignal](https://npm.io/package/react-native-onesignal.md) — 134.5K weekly downloads
- [react-redux-toastr](https://npm.io/package/react-redux-toastr.md) — 33.7K weekly downloads
- [@nocobase/plugin-notification-manager](https://npm.io/package/@nocobase/plugin-notification-manager.md) — 2.0K weekly downloads
- [react-simple-toasts](https://npm.io/package/react-simple-toasts.md) — 1.9K weekly downloads

## Recent versions

- 0.5.0 (latest) — 2025-10-29
- 0.4.100 — 2021-09-24
- 0.4.99 — 2021-09-16
- 0.4.98 — 2021-09-15
- 0.4.96 — 2021-09-15
- 0.4.94 — 2021-09-14
- 0.4.93 — 2021-09-14
- 0.4.91 — 2021-09-14
- 0.4.9 — 2021-08-13
- 0.4.8 — 2021-08-12
- 0.4.7 — 2021-08-12
- 0.4.6 — 2021-08-12
- 0.4.5 — 2021-08-03
- 0.4.4 — 2021-08-02
- 0.4.3 — 2021-08-02
- … 4 more at https://npm.io/package/@eriklenaerts/openapi-docgen/versions

## README

# Open API Document Generator

Generate new Open API documents based on your own API REST guidelines.

## Prerequisites

You have nodejs installed on your computer, if not download it here: https://nodejs.org/en/download/

## Basic usage

Open a command line terminal

```bash
> npm install -g @eriklenaerts/openapi-docgen
> mkdir your-app
> cd your-app
> openapi-docgen
```

## First time setup

For your convenience there's a command line switch to create local configuration file. (Basically a copy of the [.env.example](.env.example)).

```bash
> openapi-docgen --setup
```

Read the [configuration](#configuration) chapter below for the various options.

## Features

- Generate OAS (aka swagger) documents in JSON or YAML
- Provide resource names and it will deal with pluralisaton (English only)
- Select the operations GET, POST, PUT, ... you like for each resource
- Classify resources in specified tags
- Generates placeholder schema's for every resource
- Interactive prompt or provide command line arguments
- Generate OAS documents based on your own specifications, there's one included for the [Digipolis API System 7.0](https://antwerp-api.digipolis.be/).
- Create your own templates (based on [Handlebars](https://handlebarsjs.com/))
- Work with templates from the file system or online.

## Examples

```bash
// Show the commandline help
> openapi-docgen -h

//Generate an API called 'Appointment' the rest will be prompted
> openapi-docgen Appointment

//Generate an API called 'Appointment' with two resources 'location' and 'service'
> openapi-docgen Appointment -r 'location, service'

//Generate an API called 'Appointment' with two resources 'location' and 'tenant', the latter will be classified under the `System` tag
> openapi-docgen Appointment -r 'location, tenant::system'

//Generate an API called 'Appointment' with two resources 'location' and a sub resource 'address'
> openapi-docgen Appointment -r 'location, location/address'

//Generate an API called 'Appointment' with a resource 'address' as a sub resource, a minimal parent 'location' resource will be added with a list and read operation
> openapi-docgen Appointment -r 'location/address'

//Generate an API called 'Appointment' with two resources 'location' and 'service'. Only the list (GET collection) will be generated for the location. check out the operations modifier below
> openapi-docgen Appointment -r 'location[2], service'
```

## Calculate the Operations modifier

You can determine per resource what operations need to be generated. Simply provide a number - that is the sum of the modifiers in the table below, to modify the generator's behaviour.
This modifier can be added in square brackets with each resource in the command line.

> Tip: you can [change the default ops modifier](#configuration) yourself

To calculcate this number, use the following table:
| Operation | Description | modifier |
|----------- |-------------------------------------- |---------- |
| GET | list all resources of the collection | 1 |
| POST | add a resource to the collection | 2 |
| POST (async) | add a resource asynchronously | 4 |
| GET | retrieve a resource (by id) | 8 |
| HEAD | check if resource exist | 16 |
| PUT | replace a resource | 32 |
| PATCH | update a resource | 64 |
| DELETE | delete a resource | 128 |

Some examples:

```bash
// generate only an operation to list (GET) all locations resources
> openapi-docgen Appointment -r 'location[1]'

// generate operation to list (GET) all locations resources and delete a resource
> openapi-docgen Appointment -r 'location[129]'

// generate operation to list (GET) all locations resources, retrieve one by id (GET) and check if one exists (HEAD)
> openapi-docgen Appointment -r 'location[25]'
```

**Note:** be sure to specify the modifier on the resource itself, not on the parent indicator

```bash
// this will not work
> openapi-docgen Appointment -r 'location, location[2]/address[8]'

// this will not work either
> openapi-docgen Appointment -r 'location[2]/address[8]'

// this is what you need
> openapi-docgen Appointment -r 'location[2], location/address[8]'

// or this works as well. Basically, the generator will use [9] as a modifier for location that is, both the list and retrieve GET operations.
// (it does not make much sense to have child resources with no way to access the parent resources)
> openapi-docgen Appointment -r 'location/address[8]'
```

## Configuration

Use the .env configuration file to set the following environment variables.

> Tip: use the `--setup` command line switch to create a sample configuration file, see also [first time setup](#first-time-setup).

| Config variable         | Description                                                                                                                                    | Default value          |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
| TEMPLATE_PROVIDER       | Specify the source of the templates. ('FileSystem' or 'Online')                                                                                | FileSystem             |
| TEMPLATES_BASE_LOCATION | Set the base location for the given Template Provider.                                                                                         |                        |
| DEFAULT_TEMPLATE        | Set the default template, though the --template cli argument takes precedence.                                                                 | basic.hbs              |
| DEFAULT_OUTPUT_LOCATION | Set the default output location in case nothing was provided using the --output cli argument.                                                  | current working folder |
| UNIQUE_OUTPUT_FILENAME  | If true, each output file will have a unique part in the filename so it always writes a new file. if false, the file is overwritten each time. | false                  |
| DEFAULT_OPS_MODIFIER    | When no ops modifier was provided for a resource, use this default. Calculate the modifier [here](#calculate-the-operations-modifier)          | 235                    |

## Contribute

- Find me at https://github.com/eriklenaerts/openapi-generator
- Fork away or sent Pull Requests :v:

## Note to myself: Development

To debug:

- set `Toggle Auto Attach` to smart or always using Command Palette (`⇧⌘P`), restart Terminal, see also https://code.visualstudio.com/docs/nodejs/nodejs-debugging#_auto-attach
- open the code in Visual Studio Code.
- set breakpoints in the code
- type `node bin/generator` in a terminal

## Note to myself: Publish this package on npm

- increase version number in the `package.json` file
- ececute the `npm publish` command in a terminal
- FYI: to check all versions of this package so far on npm, execute `npm show @eriklenaerts/openapi-docgen versions --json`

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