🤖 Generator for GH repo to help you manage the OpenAPI definition lifecycle
A tool for generating multi-file OpenAPI definitions.
Need to write or contribute to an OpenAPI definition? create-openapi-repo
can help with that!
Before you begin, make sure you have the following prerequisites:
Navigate to the location where you want to create the repository.
Run one of the following commands:
Install create-openapi-repo
globally:
npm install -g create-openapi-repo
Install create-openapi-repo
using npx
:
npx create-openapi-repo
Follow the interactive prompts to complete the installation.
To upgrade from a prior version of create-openapi-repo
, run the following command in the root folder of your repository:
npx create-openapi-repo --migrate-2-3
Note: Plugins aren't included in the migration. You'll need to manually add them to the transformers
folder.
create-openapi-repo
provides interactive prompts to help guide you through the installation process. Two basic workflows are supported:
The interactive prompts allow you to specify the path to the file on your local machine, as well as rename the API (optional). After you choose to proceed, create-openapi-repo
initializes the repository and splits your OpenAPI definition into multiple files.
The interactive prompts allow you to specify a name for the API and choose whether to create a sub-folder for code sample files. After you choose to proceed, create-openapi-repo
initializes the repository and populates it with placeholder files and folders.
The directory structure will look similar to this:
Note: You can modify the directory structure to meet your specific requirements.
├── .redocly.yaml
├── LICENSE
├── README.md
├── docs
│ ├── favicon.png
│ └── index.html
├── openapi
│ ├── README.md
│ ├── code_samples
│ │ ├── C#
│ │ │ └── echo
│ │ │ └── post.cs
│ │ ├── PHP
│ │ │ └── echo
│ │ │ └── post.php
│ │ └── README.md
│ ├── components
│ │ └── README.md
│ └── paths
│ └── README.md
└── package.json
.redocly.yaml
: Configuration file for defining settings for various Redocly tools, including the lint tool and reference docs engine.openapi
: Top-level folder that contains your OpenAPI definition, openapi.yaml
entrypoint file, and sub-folders for paths
, components
, and code_samples
.code_samples
: Folder for organizing code samples into sub-folders, such as C# and PHP.components
: Folder for organizing reusable components into sub-folders, such as schema
and response
objects.paths
: Folder for organizing path definitions. Each path should be referenced from the openapi.yaml
entrypoint file.The generated repository installs a dependency for our redocly-cli
tool which supports the following commands:
npm start
: Starts the preview servernpm run build
: Bundles a multi-file OpenAPI definition into a single filenpm test
: Validates the OpenAPI definitionNote: Additional scripted shortcuts are defined in the repository's package.json
file.
Interested in contributing to this project? Here are some ways you can support us: