# create-openapi-repo: a scaffold for an OpenAPI definition

> create-openapi-repo is an MIT licensed generator that scaffolds a GitHub repository for a multi-file OpenAPI definition, with a Redocly configuration, a lint and bundle toolchain, per language code samples and a workflow for publishing reference documentation. The judgement is that the value is in the shape of the repository it produces rather than in the tool, and that the dependency list shows a project whose foundations are old but whose security overrides are current.

**Redocly/create-openapi-repo** — 🤖 Generator for GH repo to help you manage the OpenAPI definition lifecycle

- Repository: https://github.com/Redocly/create-openapi-repo
- Stars: 698 · Forks: 111
- Language: JavaScript
- License: MIT
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/redocly-create-openapi-repo

## A generator for the shape a definition deserves

create-openapi-repo is a tool for generating multi-file OpenAPI definitions, and the repository description frames it as a generator for a GitHub repository to help you manage the OpenAPI definition lifecycle.

The problem it addresses is that an API description is not one file. A real API has dozens of paths, shared schemas, reusable responses and code samples in several languages, and keeping all of that in a single YAML file is the thing people do because the tooling expects a single file. Splitting it is the right structure and it is a chore, so this project does the chore and produces a repository you can clone.

The feature list makes the scope clear. OpenAPI 3.0 support. Splitting an existing definition into multiple files, and bundling a multi-file definition back into a single file. Validation through Redocly's own openapi-cli tool, which the readme describes as free. Automated deployment of the API reference documentation with CI/CD workflows. Code samples kept as separate files. And live editing in the editor of your choice.

The two published examples are worth a look for the shape of the result, the Rebilly API definition and the Thingful one, and the readme points at the interactive prompts, which is where the workflow actually starts.

The project is MIT licensed, written in JavaScript, its version is 3.1.3, and the last push was on 2026-10-07. There are no GitHub releases, so the npm package is the artefact.

## Two workflows behind the same prompts

The usage section describes two workflows, and both go through the interactive prompts, which the readme is explicit about.

The first is splitting an existing OpenAPI definition. The prompts let you specify the path to the file on your local machine and, optionally, rename the API. After you choose to proceed, the tool initialises the repository and splits your definition into multiple files. So the existing single file is the input and the multi-file repository is the output.

The second is creating a new OpenAPI definition from nothing. The prompts ask for a name for the API and whether to create a sub-folder for code sample files, and then the tool initialises the repository and populates it with placeholder files and folders. The placeholders matter, because a repository of empty files with the right names is a structure a team can fill in, and it is a visible structure rather than an implied one.

The installation is the usual pair of routes for a generator, either a global install or the npx runner:

```bash
npm install -g create-openapi-repo
```

or npx create-openapi-repo, followed by the interactive prompts.

The prerequisites are Node.js and, for a new definition, a GitHub repository to initialise. The prompts are built with inquirer, which is why the tool asks rather than accepts flags for most of what it does.

## The generated layout mirrors the definition

The directory structure the tool produces is the interesting part, and the readme says you can modify it to meet your own requirements.

```
    ├── .redocly.yaml
    ├── LICENSE
    ├── README.md
    ├── docs
    │   ├── favicon.png
    │   └── index.html
    ├── openapi
    │   ├── README.md
    │   ├── code_samples
    │   ├── components
    │   └── paths
    └── package.json
```

The configuration file, .redocly.yaml, holds the settings for the various Redocly tools, including the lint tool and the reference documentation engine, so the repository ships with its own configuration rather than relying on a global one.

The openapi directory is the definition itself, with an openapi.yaml entry point file and three sub-folders. Components holds the reusable objects, and the readme mentions folders for schema and response objects. Paths holds the path definitions, and each one has to be referenced from the entry point, which is the one manual rule in the layout and it exists so the bundler can find the files. Code samples holds the samples, organised into sub-folders per language, and the readme shows a C# and a PHP directory with a post file in each.

The docs directory holds the favicon and the index page for the published reference documentation, and the presence of that directory beside the definition is what makes the CI deployment step a matter of configuration rather than a custom pipeline.

## Three commands and a preview server

The generated repository is not just a set of YAML files, it comes with a toolchain, because the generated package installs a dependency on Redocly's command line tool.

Three scripts are the interface. The start command launches the preview server, which is how you read the definition as documentation while you write it, and it is the reason the feature list mentions live editing in your editor of choice. The build command bundles the multi-file definition into a single file, which is what a consumer of the API needs if they are not using a bundler themselves. And the test command validates the definition.

The readme adds a note that additional scripted shortcuts are defined in the repository's package.json file, so the generated project is a starting point for your own scripts rather than a fixed set of three.

The deployment side is the other half. The feature list promises automated deployment of the API reference documentation using CI/CD workflows, and the docs directory with its index page is what such a workflow publishes. The readme also points at Redocly's commercial products for a modern documentation workflow, which is the usual arrangement for a free tool that is the front end of a paid one.

So the generated repository is a complete little project: a definition, a configuration, a preview, a bundle, a validation and a place for the documentation to land.

## Code samples live next to the paths they document

The code sample feature deserves a note, because it is the part of the layout that is not about the definition itself.

The samples are separate files, organised into sub-folders per language, and the readme's example puts a C# directory and a PHP directory under code_samples, each with a post file. The workflow is that a reader of the documentation sees a request example, follows a link to the file that produces it, and the two are edited in the same pull request.

That is a real change in how a definition is maintained, because the sample stops being a copy that goes stale and becomes a file the bundler reads. The feature list also mentions live editing in the editor of your choice, and the repository has a live-edit.gif at the root, which is the shortest possible demonstration of the point.

The second workflow asks whether to create the code sample sub-folder at all, which is the right question, because for an API with no samples the folder is noise, and the tool makes it a decision rather than a default.

The documentation for the whole flow is in the generated README files, one at the root, one inside the openapi directory and one inside code_samples, so a contributor lands in the right instructions depending on where they are working.

## Migration from the 2.x layout is not automatic

There is an upgrading section, and it contains the kind of caveat that saves an afternoon.

To upgrade from a prior version of the tool, you run a migration command in the root folder of your repository:

```bash
npx create-openapi-repo --migrate-2-3
```

And then the note that matters. Plugins are not included in the migration, and you have to add them manually to the transformers folder.

That is a significant gap in a migration, because a transformer is the thing that customises the output, and a repository that had custom transformers loses them unless you put them back by hand. The readme does not say whether the old folder is left in place or removed, so the safe assumption is to check before running it.

The rest of the upgrade story is simply the fact that the tool is a one-shot scaffold. Once the repository exists, the tool has no further part in the lifecycle, and the generated package.json scripts are the part you keep. That is worth understanding before you build a pipeline around it, because the tool is for creating a repository, not for maintaining one.

## Old foundations, current security overrides

The package manifest is a small time machine, and it is worth reading as evidence about the project's age and its maintenance.

The direct dependencies are from a few years ago. Chalk is at 2.3.1, which is the version that predates the ESM rewrite. Inquirer is at 6.2.1, and the prompt style of the interactive flow is the one from that generation. js-yaml is at 3.15.2. mkdirp is at 0.5.1, which is the version with the callback API rather than the promise one. Prettier is at 1.19.1 in the development dependencies. The engines field asks for Node 12 or newer, which is a floor that is now several years old, even though the ESLint in the same file is at 10.5.0, which is current.

What is current is the overrides block, and it is the interesting part. The package declares overrides for tmp below 0.2.6, lodash below 4.18.0, minimatch below 3.1.4 and below 5.1.7, and flatted below 3.4.2. Every one of those is a published advisory, and forcing the fixed version is the standard way to keep a package with old dependencies installable on a modern npm that refuses to install a vulnerable version.

So the shape is a tool whose foundations have not moved, with a maintainer who keeps the installable set clean. The other dependencies are the machinery of the generator, cross-spawn to run the commands, ejs for the templates, openapi-template for the layout itself, slugify for turning an API name into a repository name, yargs-parser for the flags, and lodash.isequal for comparing definitions.

## Conclusion

create-openapi-repo fits a team that is writing an OpenAPI definition across several files and wants the repository layout, the linting and the documentation pipeline already in place, because the generated project gives you a config file, a preview server, a bundle command and a validation command on the first run. It is the wrong choice if you already have a working setup, since the tool is a one-shot scaffold rather than something you keep running, and it is the wrong choice if you need OpenAPI 3.1, because the feature list says 3.0 support. Before you generate a repository with it, read the migration notes for anything older than the 3.x layout, because the plugins are not migrated for you, and check the engine requirement, since the package still declares Node 12 as its floor even though the lint tooling has moved on.

## FAQ

### What does create-openapi-repo do?

It generates a GitHub repository for a multi-file OpenAPI definition. It can split an existing single-file definition into multiple files or create a new definition from placeholders, and the generated repository includes a Redocly configuration, a lint, build and preview toolchain, per language code sample folders and a place for reference documentation to be published.

### How do I install and run it?

With Node.js and, for a new definition, a GitHub repository ready. Run npm install -g create-openapi-repo or npx create-openapi-repo and follow the interactive prompts, which ask for the path to an existing definition or for a name and whether to create a code samples folder.

### Which OpenAPI versions are supported?

The feature list states OpenAPI 3.0 support. The tool is for OpenAPI 3.0 definitions, and the repository's topics also name OpenAPI 3.1, so a 3.1 definition is a case to check before you rely on the generated linting and bundling.

### What happens to my custom transformers when I upgrade?

They are not migrated. The readme says to run npx create-openapi-repo --migrate-2-3 in the root of the repository, and warns that plugins are not included in the migration, so they have to be added manually to the transformers folder.

## Sources

- [Issues](https://github.com/Redocly/create-openapi-repo/issues)
- [License: MIT](https://github.com/Redocly/create-openapi-repo/blob/master/LICENSE)
- [README](https://github.com/Redocly/create-openapi-repo/blob/master/README.md)
- [Redocly/create-openapi-repo on GitHub](https://github.com/Redocly/create-openapi-repo)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/redocly-create-openapi-repo