peter-evans/swagger-github-pages

How to host Swagger API documentation with GitHub Pages

How to host Swagger API documentation with GitHub Pages

This repository is a template for using the 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.

The example API specification used by this repository can be seen hosted at 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.

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 and change the url property to reference your local YAML file.

       window.ui = SwaggerUIBundle({
           url: "swagger.yaml",
       ...

   Then fix any references to files in the "dist" directory.

   ...
   <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.

   

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.

swagger-github-pages's Issues

Remote swagger file?

Does this repo support pulling an openApi file from a hosted URL, rather than a local file? If not, could it?

In case it helps, my use case is that I have an existing private repo with an auto-generated openApi.yml file. I'd LOVE to add a swagger ui github page to it, but making the repo public isn't an option. I'm working around it right now via scripting by copying over the file contents into the public swagger-ui repo, but it would be much easier if I were able to host the API spec outside the repo and point to it :)

Swagger config file

Is it possible to add swagger config file (swagger-config.json)?

I have tried adding swagger-config.json to the root, as well as the dist/ but SwaggerUIBandle doesn't find it. Or atleast it doesn't change anything.

I need this to specify operationsSorter parameter of the SwaggerUI

Swagger hosted via github page gives ERR_CERT_COMMON_NAME_INVALID

1. Host any swagger via github pages
2. Swagger is hosted @ https://peter-evans.github.io/swagger-github-pages/
3. Click on Try it out option
4. It doesn't work and responds with FAILED to fetch
5. Open console and observe ERR_CERT_COMMON_NAME_INVALID

This may be because the swagger is hosted on one domain and the API that's being testing on another domain. How to resolve this ?

Copy button is not indicating the text was copied or not

Hello Team,

After clicking on the copy button its not showing the text like "copied", i wanted to customized this one , can you help us..
Swagger-ui:@^4.15.5,
react:@^17.0.2

Is this work with springdoc-openapi

Hi, is this Swagger template works with springdoc-openapi variation of Swagger?

Swagger UI GitHub Action

I created a Swagger UI GitHub Action which can be used to automatically generate the Swagger UI static html files based on a spec file and a swagger-config file. The generated Swagger UI is customizable via GitHub Actions inputs and the output can be deployed to GitHub Pages. The Action can be used in the same repository as the REST API service itself and be automatically updated with generated spec files with every push to the git repository.

I used this repository as inspiration to build the Action and how to download and generate the files of the swagger ui. I just wanted to add this here as an alternative to setting up this template repository and customizing swagger ui by hand.

License seems to be missing

Hi @peter-evans ,

thank you for this nice template!

Would you mind adding a LICENSE file?
That would help adoption in certain cases.
In case there is a license mentioned and I've not seen it, I apologize and am happy to take any hint as where to find it.

Thank you,
Ole

Load external in api specs

Hi,
Your repo is so great. I'm following your guide lines to setup my repo. And i found an issue when using external refs in api spec yaml file. It's look like the swagger-ui cannot load the external files, maybe it because of hosting deployment.
I defined external refs in examples of request

            examples:
               response:
                 externalValue: ./token_balances/_TokenBalancesResponse.json
      

Can you give some recommendation for finding solution for this issue

Changing the logo

Really enjoying using this project, massive help.

I was wondering if you could help in how to change the default logo on the page.