generator-openapi-repo

generator-openapi-repo

Yeoman generator for OpenAPI(fka Swagger) repo to help you share spec for your API

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 Swagger spec into smaller files and bundle it for deployment
• Continuous integration/deployment on Travis
• Code samples as separate files
• Swagger spec is validated after each commit
• Swagger 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.

• First, install Yeoman and generator-openapi-repo:

npm install -g yo
npm install -g generator-openapi-repo

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

yo openapi-repo

• Commit and push your changes to the GitHub and follow instruction from README.md of your newly created repo. Note: don't forget to commit the .yo-rc.json file, it contains all answers gave to yeoman, and they are reused during the update procedure.

Updating an existing project

• First make sure you have committed everything or have a backup
• Run yo openapi-repo over the project again
• yo will ask you for each file if you want to overwrite
• For those files you haven't edited, just say yes
• For the other ones, type d for diff and see what's changed