πŸ€– Yeoman generator for OpenAPI/Swagger repo to help you share spec for your API
Clone or download

README.md

generator-openapi-repo NPM version Dependency Status

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

logo

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 πŸ˜„)

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 😍 live editing

Examples of generated repositories

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