create-openapi-repo

by Redocly

πŸ€– Generator for GH repo to help you manage the OpenAPI definition lifecycle

458 Stars 74 Forks Last release: Not found MIT License 134 Commits 4 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

create-openapi-repo

NPM version Dependency Status

Generate an organized multi-file OpenAPI repository.

Who?

You! Hello. Do you need to write or contribute to an OpenAPI definition? If so, read on...

What?

We recommend a docs-like-code approach to OpenAPI definitions: - Write it using your favorite text-editor or IDE (we love VSCode). - Organize it into multiple files and folders to make it easy to navigate. - Store it using source control (such as GitHub). - Continuously validate it using our free openapi-cli tool or our free continuous validation service (coming soon). - Bundle it (for a smaller footprint to use in other tools or for tools that do not support a multi-file format).

Why?

There are a few advantages in hosting your API definition on GitHub: - Community engagement (PR's and issues -- if you have a public repo) - Advertisment in the GitHub community - Hosting on GitHub pages (perfect uptime, CDN, Jekyll, custom domains with CNAME) - Revision history, branching, CI - Review and approval workflows using Pull Requests - Fast on-boarding time (developers and tech writers know how to use GitHub :smile:) - Fully compatible with Redocly API Reference too

There are also some advantages to a multi-file YAML format OpenAPI definition: - Reuse schema objects to keep things DRY (don't repeat yourself) - Smaller diffs compared to JSON (especially for markdown descriptions) - Easier to navigate - Easier to edit with confidence

Features

This generator helps to create a GitHub repo with the following features: - Split a big (or small) OpenAPI definition into smaller files organized into folders - Bundle it into a single file for deployment - Continuous integration/deployment on Travis or Redocly Workflows - Code samples as separate files - Automate deployment of your OpenAPI definition and docs - OpenAPI definition is validated after each commit - Live editing in your editor of choice :heart_eyes:

Structure

You will have a structure similar to this:

    β”œβ”€β”€ .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

However, you can adjust it to any structure you prefer.

The

openapi
folder is where your OpenAPI definition will live. Inside there, and the sub-folders, there are
README.md
files to help guide you further. This is also where your entrypoint
openapi.yaml
will live.

The

components
folder is where you will organize sub-folders such as
schema
to define your schema.

The

paths
folder is where you will organize your paths. There will be a 'README.md' file in there with suggestions for how to organize it into specially named files (or folders) that use an
@
in place of a
/
(because files cannot have a
/
character in them). You will also be able to use path parameters by wrapping them in curly braces
{example}
.

The

.redocly.yaml
file is a universal configuration for various Redocly tools including the lint tool and reference doc engine.

Commands

The generated repository includes installing a dependency for our

openapi-cli
tool which supports commands such as
validate
,
bundle
, and more. There are scripted shortcuts defined in the repository's
package.json
.

Examples of generated repositories

  • https://github.com/Rebilly/RebillyAPI
  • https://github.com/thingful/openapi-spec
  • https://github.com/TwineHealth/TwineDeveloperDocs

How to generate your repository

We assume you already have node.js installed.

  • Install
    create-openapi-repo
    globally:
    bash
    npm install -g create-openapi-repo
    
    or use
    npx
    :

We'll use

npx
in this example. However, remove
npx
if you installed it globally.
npx create-openapi-repo

You will be presented with some questions. You can create a new definition or use an existing definition to initialize your project.

Please note, if you do start a new one, remember to create a GitHub repo where your OpenAPI definition will live.

If you use the prior version of this generated repository, please read the following upgrade instructions.

Upgrading from a prior version

Migrate your repository from a previous structure of OpenAPI repo to this newer structure with our migration tool.

Run this in the root folder of your repo.

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

Note: the migration tool does not migrate plugins automatically. You would need to manually add them to the

transformers
folder.

Support

Thank you for wanting to support us. Here are some ideas how to support us:

  • Star us
  • Tell a friend or colleague about us (or Tweet about us)
  • Write an article about it (and let us know) -- open an issue to let us know, with the link.
  • Consider our commercial products if are looking for automation to ease the docs-like code workflow, hosting along with conveniences like custom domains, access controls and previews, API reference documentation, or a full developer portal: https://redoc.ly

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.