generated from peter-evans/swagger-github-pages
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
4 changed files
with
273 additions
and
762 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,23 @@ | ||
# Swagger Codegen Ignore | ||
# Generated by swagger-codegen https://github.com/swagger-api/swagger-codegen | ||
|
||
# Use this file to prevent files from being overwritten by the generator. | ||
# The patterns follow closely to .gitignore or .dockerignore. | ||
|
||
# As an example, the C# client generator defines ApiClient.cs. | ||
# You can make changes and tell Swagger Codgen to ignore just this file by uncommenting the following line: | ||
#ApiClient.cs | ||
|
||
# You can match any string of characters against a directory, file or extension with a single asterisk (*): | ||
#foo/*/qux | ||
# The above matches foo/bar/qux and foo/baz/qux, but not foo/bar/baz/qux | ||
|
||
# You can recursively match patterns against a directory, file or extension with a double asterisk (**): | ||
#foo/**/qux | ||
# This matches foo/bar/qux, foo/baz/qux, and foo/bar/baz/qux | ||
|
||
# You can also negate patterns with an exclamation (!). | ||
# For example, you can ignore all files in a docs folder with the file extension .md: | ||
#docs/*.md | ||
# Then explicitly reverse the ignore rule for a single file: | ||
#!docs/README.md |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1 @@ | ||
3.0.56 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,58 +0,0 @@ | ||
# How to host Swagger API documentation with GitHub Pages | ||
[<img alt="The blog of Peter Evans: How to Host Swagger Documentation With Github Pages" title="View blog post" src="https://peterevans.dev/img/blog-published-badge.svg">](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. | ||
|
||
![Headers](/screenshots/swagger-github-pages.png?raw=true) | ||
|
||
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 | ||
... | ||
<link rel="stylesheet" type="text/css" href="dist/swagger-ui.css" > | ||
<link rel="icon" type="image/png" href="dist/favicon-32x32.png" sizes="32x32" /> | ||
<link rel="icon" type="image/png" href="dist/favicon-16x16.png" sizes="16x16" /> | ||
... | ||
<script src="dist/swagger-ui-bundle.js"> </script> | ||
<script src="dist/swagger-ui-standalone-preset.js"> </script> | ||
... | ||
``` | ||
6. Go to the settings for your repository at `https://github.com/{github-username}/{repository-name}/settings` and enable GitHub Pages. | ||
![Headers](/screenshots/swagger-github-pages.png?raw=true) | ||
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/). | ||
Oops, something went wrong.