https://github.com/rustysnek/restapi-specs
https://github.com/rustysnek/restapi-specs
Last synced: 4 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/rustysnek/restapi-specs
- Owner: RustySnek
- Created: 2023-09-04T17:30:27.000Z (almost 3 years ago)
- Default Branch: master
- Last Pushed: 2023-09-04T17:38:54.000Z (almost 3 years ago)
- Last Synced: 2023-09-05T06:03:25.320Z (almost 3 years ago)
- Language: HTML
- Size: 800 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
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/).