create-openapi-repo

Generator for OpenAPI repository

Why?

There are a few advantages in hosting your API specification + docs on GitHub:

• Community engagement (PR's and issues)
• Hosting on GitHub pages (perfect uptime, CDN, Jekyll, custom domains with CNAME)
• Advertisment in the GitHub community
• Revision history, branching, CI
• Fast on-boarding time (everyone knows how to use GitHub :smile:)

Features

This generator helps to create a GitHub repo with the following features:

• Possibility to split a big OpenAPI spec into smaller files and bundle it for deployment
• Continuous integration/deployment on Travis
• Code samples as separate files
• OpenAPI spec is validated after each commit
• OpenAPI spec + ReDoc deployed to Github Pages (you can use a custom domain)
• Live editing in your editor or swagger-editor :heart_eyes:

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:

npm install -g create-openapi-repo

or use npx:

npx create-openapi-repo <spec-root>

• Create GitHub repo where your OpenAPI spec will live.
• Clone your repo and execute the following command inside it:

create-openapi-repo .

• Commit and push your changes to the GitHub and follow instruction from README.md of your newly created repo.