Repository files navigation

A tool for generating multi-file OpenAPI definitions.

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

• 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 freeopenapi-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 😍

• Rebilly
• Thingful

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

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

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

2. Run one of the following commands:

   • Installcreate-openapi-repo globally:

     npm install -g create-openapi-repo

   • Installcreate-openapi-repo usingnpx:

     npx create-openapi-repo

3. Follow theinteractive prompts to complete the installation.

To upgrade from a prior version ofcreate-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 thetransformers 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 forpaths,components, andcode_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 asschema andresponse objects.
• paths: Folder for organizing path definitions. Each path should be referenced from theopenapi.yaml entrypoint file.

The generated repository installs a dependency for ourredocly-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'spackage.json file.

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? Ourcommercial products can help you maintain and deploy API reference docs and developer portals.