https://github.com/two02/vimzy-docs
https://github.com/two02/vimzy-docs
Last synced: about 2 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/two02/vimzy-docs
- Owner: two02
- License: mit
- Created: 2024-03-19T06:13:18.000Z (over 2 years ago)
- Default Branch: master
- Last Pushed: 2024-04-19T10:16:29.000Z (about 2 years ago)
- Last Synced: 2024-04-19T12:09:13.579Z (about 2 years ago)
- Language: HTML
- Homepage: https://two02.github.io/vimzy-docs/
- Size: 2.03 MB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
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/).