|
1 | | -# How to host Swagger API documentation with GitHub Pages |
2 | | -[<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/) |
3 | | - |
4 | | -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. |
5 | | - |
6 | | -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). |
7 | | - |
8 | | -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/). |
9 | | - |
10 | | -## Steps to use this template |
11 | | - |
12 | | -1. Click the `Use this template` button above to create a new repository from this template. |
13 | | - |
14 | | -2. Go to the settings for your repository at `https://github.com/{github-username}/{repository-name}/settings` and enable GitHub Pages. |
15 | | - |
16 | | -  |
17 | | - |
18 | | -3. Browse to the Swagger documentation at `https://{github-username}.github.io/{repository-name}/`. |
19 | | - |
20 | | - |
21 | | -## Steps to manually configure in your own repository |
22 | | - |
23 | | -1. Download the latest stable release of the Swagger UI [here](https://github.com/swagger-api/swagger-ui/releases). |
24 | | - |
25 | | -2. Extract the contents and copy the "dist" directory to the root of your repository. |
26 | | - |
27 | | -3. Move the file "index.html" from the directory "dist" to the root of your repository. |
28 | | - ``` |
29 | | - mv dist/index.html . |
30 | | - ``` |
31 | | - |
32 | | -4. Copy the YAML specification file for your API to the root of your repository. |
33 | | -
|
34 | | -5. Edit [index.html](index.html) and change the `url` property to reference your local YAML file. |
35 | | - ```javascript |
36 | | - const ui = SwaggerUIBundle({ |
37 | | - url: "swagger.yaml", |
38 | | - ... |
39 | | - ``` |
40 | | - Then fix any references to files in the "dist" directory. |
41 | | - ```html |
42 | | - ... |
43 | | - <link rel="stylesheet" type="text/css" href="dist/swagger-ui.css" > |
44 | | - <link rel="icon" type="image/png" href="dist/favicon-32x32.png" sizes="32x32" /> |
45 | | - <link rel="icon" type="image/png" href="dist/favicon-16x16.png" sizes="16x16" /> |
46 | | - ... |
47 | | - <script src="dist/swagger-ui-bundle.js"> </script> |
48 | | - <script src="dist/swagger-ui-standalone-preset.js"> </script> |
49 | | - ... |
50 | | - ``` |
51 | | - |
52 | | -6. Go to the settings for your repository at `https://github.com/{github-username}/{repository-name}/settings` and enable GitHub Pages. |
53 | | -
|
54 | | -  |
55 | | - |
56 | | -7. Browse to the Swagger documentation at `https://{github-username}.github.io/{repository-name}/`. |
57 | | -
|
58 | | - 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/). |
| 1 | +<div align=left> |
| 2 | + <h1>Redmine Swagger API</h1> |
| 3 | + <p>A swagger api definition for the redmine rest API. |
| 4 | + Work in progress</p> |
| 5 | +</div> |
| 6 | +<p align="left"> |
| 7 | + <a target="_blank" href="https://morpheus235.github.io/redmine-swagger-api/" alt="Swagger-API"> |
| 8 | + <img src="https://img.shields.io/badge/Github%20Page-Swagger--UI-informational" /></a> |
| 9 | + </p> |
| 10 | + |
| 11 | + |
| 12 | + |
| 13 | +### Usage |
| 14 | + |
| 15 | +```shell |
| 16 | +git clone https://github.com/Morpheus235/redmine-swagger-api |
| 17 | +``` |
| 18 | +#### OR |
| 19 | + |
| 20 | +```shell |
| 21 | +https://morpheus235.github.io/redmine-swagger-api/swagger.yaml |
| 22 | +``` |
| 23 | +### Useful links: |
| 24 | +#### Swagger Codegen |
| 25 | +- https://swagger.io/tools/swagger-codegen/ |
| 26 | +#### Swagger Docs |
| 27 | +- https://swagger.io/docs/ |
0 commit comments