redocly / create-openapi-repo

🤖 Generator for GH repo to help you manage the OpenAPI definition lifecycle

create-openapi-repo

A tool for generating multi-file OpenAPI definitions.

Need to write or contribute to an OpenAPI definition? create-openapi-repo can help with that!

Features

• OpenAPI 3.0 support
• Split an existing OpenAPI definition into multiple files
• Bundle a multi-file definition into a single file
• Validate your OpenAPI definition using our free openapi-cli tool
• Automate deployment of your API reference docs using CI/CD workflows
• Maintain code samples as separate files
• Live editing in your editor of choice 😍

Examples

• Rebilly
• Thingful

Prerequisites

Before you begin, make sure you have the following prerequisites:

• Node.js
• Github repository (new OpenAPI definitions only)

Installation

1. Navigate to the location where you want to create the repository.

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

3. Follow the interactive prompts to complete the installation.

Upgrading from a prior version

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.

Usage

create-openapi-repo provides interactive prompts to help guide you through the installation process. Two basic workflows are supported:

Split an existing OpenAPI definition

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.

Create a new OpenAPI definition

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.

Directory structure

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.

Commands

The generated repository installs a dependency for our redocly-cli tool which supports the following commands:

• npm start: Starts the preview server
• npm run build: Bundles a multi-file OpenAPI definition into a single file
• npm test: Validates the OpenAPI definition

Note: Additional scripted shortcuts are defined in the repository's package.json file.

Contribute

Interested in contributing to this project? Here are some ways you can support us:

• Submit a pull request.
• Star us on Github.
• Tell a friend or colleague about us (or Tweet about us).
• Write an article or blog post. Let us know by opening an issue with a link to the article.
• Looking to build a modern documentation workflow? Our commercial products can help you maintain and deploy API reference docs and developer portals.