OK, you are on the swagger.io site so you might be planning to write an OpenAPI specification for your API or you already have the one. How about publishing it on GitHub?
Publishing specification on GitHub
GitHub repository with OpenAPI specification has several benefits:
- Hosting on GitHub Pages (perfect uptime, CDN, Jekyll, custom domains with CNAME)
- Advertisement in the GitHub community
- Revision history, branching, CI
- Fast onboarding time (everyone knows how to use GitHub ?)
But the main advantage is community engagement: your API users can provide feedback by opening PR's and issues! See how it works for Spotify on the screenshot below:
Many big players have already followed this trend:
It's very easy to create GitHub repository and put your spec there, but at some time you will have to implement features like validation, docs generating, deployment, etc.
We've got you covered!
We at APIs.guru were contracted to set up such repo for Rebilly Inc. Rebilly liked our solution and asked for such repositories for their internal/experimental APIs. They were so kind to sponsor development of generator-openapi-repo - open-source automatic generator for GitHub hosted API portals.
All you need to set up such repository is to run our tool and answer a few very simple questions:
Try it now!
It's so simple we encourage you to TRY IT RIGHT NOW.
In less than 20 minutes you will have an API repository hosted on GitHub with the following neat features:
- Continuous integration/deployment on Travis
- Support for Code samples as separate files
- OpenAPI specification validation after each commit
- ReDoc + SwaggerUI hosted on Github Pages (you can use a custom domain)
- Live editing in your favorite editor or in swagger-editor ?
Feel free to open issues and feature requests on GitHub repository.