https://github.com/peter-evans/swagger-github-pages
How to host Swagger API documentation with GitHub Pages
https://github.com/peter-evans/swagger-github-pages
api-documentation github-pages swagger swagger-ui
Last synced: 2 months ago
JSON representation
How to host Swagger API documentation with GitHub Pages
- Host: GitHub
- URL: https://github.com/peter-evans/swagger-github-pages
- Owner: peter-evans
- License: mit
- Created: 2018-05-02T08:21:52.000Z (about 7 years ago)
- Default Branch: master
- Last Pushed: 2024-05-01T10:30:18.000Z (about 1 year ago)
- Last Synced: 2024-05-02T02:15:27.660Z (about 1 year ago)
- Topics: api-documentation, github-pages, swagger, swagger-ui
- Language: HTML
- Size: 173 MB
- Stars: 411
- Watchers: 4
- Forks: 116
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# How to host Swagger API documentation with GitHub Pages
[
](https://peterevans.dev/posts/how-to-host-swagger-docs-with-github-pages/)
This repository is a template for using the [Swagger UI](https://github.com/swagger-api/swagger-ui) to dynamically generate beautiful documentation for your API and host it for free with GitHub Pages.
The template will periodically auto-update the Swagger UI dependency and create a pull request. See the [GitHub Actions workflow here](.github/workflows/update-swagger.yml).
The example API specification used by this repository can be seen hosted at [https://peter-evans.github.io/swagger-github-pages](https://peter-evans.github.io/swagger-github-pages/).
## Steps to use this template
1. Click the `Use this template` button above to create a new repository from this template.
2. Go to the settings for your repository at `https://github.com/{github-username}/{repository-name}/settings` and enable GitHub Pages.
3. Browse to the Swagger documentation at `https://{github-username}.github.io/{repository-name}/`.
## Steps to manually configure in your own repository
1. Download the latest stable release of the Swagger UI [here](https://github.com/swagger-api/swagger-ui/releases).
2. Extract the contents and copy the "dist" directory to the root of your repository.
3. Move the file "index.html" from the directory "dist" to the root of your repository.
```
mv dist/index.html .
```
4. Copy the YAML specification file for your API to the root of your repository.
5. Edit [dist/swagger-initializer.js](dist/swagger-initializer.js) and change the `url` property to reference your local YAML file.
```javascript
window.ui = SwaggerUIBundle({
url: "swagger.yaml",
...
```
Then fix any references to files in the "dist" directory.
```html
...
...
...
```
6. Go to the settings for your repository at `https://github.com/{github-username}/{repository-name}/settings` and enable GitHub Pages.
7. Browse to the Swagger documentation at `https://{github-username}.github.io/{repository-name}/`.
The example API specification used by this repository can be seen hosted at [https://peter-evans.github.io/swagger-github-pages](https://peter-evans.github.io/swagger-github-pages/).