How to open local files in Swagger-UI

Question

I'm trying to open my self generated swagger specification file my.json with swagger-ui on my local computer.

So I downloaded the latest tag v2.1.8-M1 and extracted the zip. Then I went inside the sub folder dist and copied the file my.json into it. Now I opened the index.html and want to explore my.json. And here the problem begins:

If I enter a local path, it always will be prefixed by the current url containing the index.html. And therefor I can't open my file. I tried all following combinations without success:

my.json leads to file:///D:/swagger-ui/dist/index.html/my.json
file:///D:/swagger-ui/dist/my.json leads to file:///D:/swagger-ui/dist/index.html/file:///D:/swagger-ui/dist/my.json

You actually don't need to host your Swagger UI in order to view Swagger spec. I have written an article which explains how you can use online available petstore Swagger UI to view your swagger spec. Check this out - https://medium.com/@requestly_ext/check-swagger-api-specs-without-hosting-swagger-ui-934861c004de — Sachin Jain, Dec 07 '17 at 07:30

score 74 · Answer 1 · answered Nov 11 '15 at 19:16

74

I could not get Adam Taras's answer to work (i.e. using the relative path ../my.json).

Here was my solution (pretty quick and painless if you have node installed):

With Node, globally install package http-server npm install -g http-server
Change directories to where my.json is located, and run the command http-server --cors (CORS has to be enabled for this to work)
Open swagger ui (i.e. dist/index.html)
Type http://localhost:8080/my.json in input field and click "Explore"

answered Nov 11 '15 at 19:16

MandM

3,293
4
34
56

13

This is atrocious design. Why not just make Swagger UI run on a local node server? – Kenny Worden Jun 16 '16 at 19:46
@KennyWorden, because that doesn't work - maybe test next time? Hosting Swagger UI on a local node server works fine, but then if I put in the local path to the API, i.e. "file:///path/to/api.json", the UI auto-appends "http://localhost:8080/file:///path/to/api.json" - obviously this path doesn't work. I could move the API to the same directory, type in "my.json", but copying the API to the Swagger UI location isn't necessarily "beautiful" either - any variation of this is ugly. It may make you feel better personally, but I'd rather have less steps that work reliably. – MandM Jun 28 '16 at 18:33
1

Thanks. That's exactly what I was missing. The `--cors` parameter. I used it with a docker image connecting to http-server perfectly. Thanks again. – Darren Jul 01 '16 at 12:09
2

Well this was a bit of a crash course on how http servers work, but I managed to get it all running. Thanks! – Shadoninja Nov 08 '16 at 22:28
5

Recommend `http-server --cors -a 127.0.0.1` to prevent anyone else on the network from browsing your directory index. – Ben Whaley Apr 25 '19 at 21:02
1

Maybe it could be useful to someone, latest standalone swagger release link for download https://github.com/swagger-api/swagger-ui/releases/latest – Antimo Apr 23 '21 at 07:52

paragbaxi · Answer 2 · 2019-10-23T17:34:37.493

Use the spec parameter.

Instructions below.

Create spec.js file containing Swagger JSON

Create a new javascript file in the same directory as index.html (/dist/)

Then insert spec variable declaration:

var spec =

Then paste in the swagger.json file contents after. It does not have to be on the same line as the = sign.

Example:

var spec =

{
    "swagger": "2.0",
    "info": {
        "title": "I love Tex-Mex API",
        "description": "You can barbecue it, boil it, broil it, bake it, sauté it. Dey's uh, Tex-Mex-kabobs, Tex-Mex creole, Tex-Mex gumbo. Pan fried, deep fried, stir-fried. There's pineapple Tex-Mex, lemon Tex-Mex, coconut Tex-Mex, pepper Tex-Mex, Tex-Mex soup, Tex-Mex stew, Tex-Mex salad, Tex-Mex and potatoes, Tex-Mex burger, Tex-Mex sandwich..",
        "version": "1.0.0"
    },
    ...
    }
}

Modify Swagger UI index.html

This is a two-step like Ciara.

Include spec.js

Modify the /dist/index.html file to include the external spec.js file.

 <script src='spec.js' type="text/javascript"></script>

Example:

  <!-- Some basic translations -->
  <!-- <script src='lang/translator.js' type='text/javascript'></script> -->
  <!-- <script src='lang/ru.js' type='text/javascript'></script> -->
  <!-- <script src='lang/en.js' type='text/javascript'></script> -->

  <!-- Original file pauses -->
  <!-- Insert external modified swagger.json -->
  <script src='spec.js' type="text/javascript"></script>
  <!-- Original file resumes -->

  <script type="text/javascript">

    $(function () {
      var url = window.location.search.match(/url=([^&]+)/);
      if (url && url.length > 1) {
        url = decodeURIComponent(url[1]);
      } else {
        url = "http://petstore.swagger.io/v2/swagger.json";
      }

Add spec parameter

Modify the SwaggerUi instance to include the spec parameter:

  window.swaggerUi = new SwaggerUi({
    url: url,
    spec: spec,
    dom_id: "swagger-ui-container",

This gives the following error: Finished Loading Resource Information. Rendering Swagger UI... — Ayushi Dalmia, Aug 31 '16 at 06:19
This works nicely without having to mess with `npm` and keeps the ability to locally host the `dist/` folder which is sort of the whole point. — syvex, Mar 02 '18 at 16:38
does this only work with JSON specs? doesn't seem to work with YAML specs at first glance. — Sean Azlin, Jul 15 '22 at 18:00

score 20 · Answer 3 · answered Jun 26 '17 at 06:59

After a bit of struggle, I found a better solution.

create a directory with name: swagger
```
mkdir C:\swagger
```

If you are in Linux, try:

    mkdir /opt/swagger

get swagger-editor with below command:

git clone https://github.com/swagger-api/swagger-editor.git

go into swagger-editor directory that is created now
```
cd swagger-editor
```

now get swagger-ui with below command:

git clone https://github.com/swagger-api/swagger-ui.git

now, copy your swagger file, I copied to below path:
```
./swagger-editor/api/swagger/swagger.json
```
all setup is done, run the swagger-edit with below commands
```
npm install
npm run build
npm start
```
You will be prompted 2 URLs, one of them might look like:
```
http://127.0.0.1:3001/
```
Above is swagger-editor URL
Now browse to:
```
http://127.0.0.1:3001/swagger-ui/dist/
```
Above is swagger-ui URL

Thats all.

You can now browse files from either of swagger-ui or swagger-editor

It will take time to install/build, but once done, you will see great results.

It took roughly 2 days of struggle for me, one-time installation took only about 5 minutes.

Now, on top-right, you can browse to your local file.

best of luck.

Thanks. Just a note. Since we are running under nodejs in this scenario, we don't really read the files from the disk but use the URL, example: http://10.0.60.76:3001/swagger-ui/myfile.json (type this not in the URL of the browser, but in the file to open to the left of the Explore button, then click Explore). But I imagine most people just want to use the swagger-ui on the swagger site, then open a disk file on their computer (which would not be a URL). — NealWalters, Mar 15 '18 at 20:22
http://127.0.0.1:3001/swagger-ui/dist/ just gives me a lot of redirects until it fails. http://127.0.0.1:3001/swagger-ui/dist/index.html works and there I need to paste http://127.0.0.1:3001/swagger-ui/dist/api/swagger/swagger.json to Explore field and click the Explore button. — Panu Haaramo, Jan 16 '20 at 14:01

score 20 · Answer 4 · answered Dec 05 '18 at 12:42

20

In a local directory that contains the file ./docs/specs/openapi.yml that you want to view, you can run the following to start a container and access the spec at http://127.0.0.1:8246.

docker run -t -i -p 8246:8080 -e SWAGGER_JSON=/var/specs/openapi.yml -v $PWD/docs/specs:/var/specs swaggerapi/swagger-ui

answered Dec 05 '18 at 12:42

simesy

410
3
9

1

This worked for me too. Do you know how we can remove the top bar in the swagger UI so it doesnt show the URL location of the swagger file? – Sakib Nov 22 '19 at 20:38
2

for people on windows: replace `$PWD` with `%cd%` – erncyp Feb 03 '20 at 15:27
1

@Sakib you would need to extend or modify the docker image to do that. A bit involved to explain in a comment. – simesy Feb 04 '20 at 01:38
@erncyp `$PWD` will also work on Windows when you're in PowerShell. – Moritz Oct 21 '22 at 12:15

score 11 · Answer 5 · answered Jan 22 '20 at 06:29

11

If all you want is just too see the the swagger doc file (say swagger.json) in swagger UI, try open-swagger-ui (is essentially, open "in" swagger ui).

open-swagger-ui ./swagger.json --open

answered Jan 22 '20 at 06:29

Wajahath

2,827
2
28
37

2

Thanks! That is probably the easiest option if you just want to visualize your swagger.json file – Rayee Roded Apr 15 '20 at 15:39
This is good, but it's broken for basePath – Benyamin Limanto Oct 27 '22 at 14:36

score 11 · Answer 6 · answered Apr 14 '22 at 13:59

11

Simplest way

1/ Run

npx open-swagger-ui <path or URL>

2/ Navigate to http://localhost:3355/

answered Apr 14 '22 at 13:59

Samuel Rossille

18,940
18
62
90

100% the easiest way. First time and it worked! – Eitel Dagnin Jun 16 '22 at 05:53
Easy and fast. Underrated answer :p – ChristopheBrun Aug 25 '22 at 10:06
Not good enough for us who want to host it for various reasons. For example we require local authentication to access the documentation. – Spock Mar 23 '23 at 13:28
Anyone knows how to combine the above with CORS? – Anders Apr 03 '23 at 08:57
Definitely *the* answer. If I could upvote multiple times I would. – Michael Krauklis Jun 06 '23 at 17:20

Adam Taras · Accepted Answer · 2017-08-02T08:20:25.927

4

What works, is to enter a relative path or an absolute without the file://-protocol:

../my.json leads to file:///D:/swagger-ui/dist/index.html/../my.json and works
/D:/swagger-ui/dist/my.json leads to file:///D:/swagger-ui/dist/my.json and works

HINT

This answer works with Firefox on Win7. For Chrome-Browser, see comments below:

edited Aug 02 '17 at 08:20

answered May 22 '15 at 15:22

Adam Taras

1,403
1
13
15

6

Chrome needs to be started with --allow-file-access-from-files argument or with --disable-web-security argument to make this hint work. – Aleksey Korolev Jun 27 '15 at 22:31
2

how do I make it so that the user doesn't need to enable --alow-file-access. I will be sending a .zip file to multiple people – Angular Jul 19 '16 at 20:50

score 3 · Answer 8 · answered Nov 14 '15 at 12:33

I had that issue and here is much simpler solution:

Make a dir (eg: swagger-ui) in your public dir (static path: no route is required) and copy dist from swagger-ui into that directory and open localhost/swagger-ui
You will see swagger-ui with default petstore example
Replace default petstore url in dist/index.html with your localhost/api-docs or to make it more generalized, replace with this:

location.protocol+'//' + location.hostname+(location.port ? ':' + location.port: '') + "/api-docs";
Hit again localhost/swagger-ui

Voila! You local swagger implementation is ready

score 3 · Answer 9 · edited Oct 28 '20 at 15:13

LINUX

I always had issues while trying paths and the spec parameter.

Therefore I went for the online solution that will update automatically the JSON on Swagger without having to reimport.

If you use npm to start your swagger editor you should add a symbolic link of your json file.

cd /path/to/your/swaggerui where index.html is.

ln -s /path/to/your/generated/swagger.json

You may encounter cache problems. The quick way to solve this was to add a token at the end of my url...

window.onload = function() {

var noCache = Math.floor((Math.random() * 1000000) + 1);

// Build a system
const editor = SwaggerEditorBundle({
url: "http://localhost:3001/swagger.json?"+noCache,
  dom_id: '#swagger-editor',
  layout: 'StandaloneLayout',
  presets: [
    SwaggerEditorStandalonePreset
  ]
})

window.editor = editor
}

Also, need to change `SwaggerEditorBundle`'s `url` to relative path of swagger.json file. — Eric, May 05 '21 at 07:06

score 3 · Answer 10 · edited Feb 22 '22 at 15:54

I managed to load the local swagger.json specification using the following tools for Node.js and this will take hardly 5 minutes to finish

swagger-ui-dist

express

Follow below steps

Create a folder as per your choice and copy your specification swagger.json to the newly created folder
Create a file with the extension .js in my case swagger-ui.js in the same newly created folder and copy and save the following content in the file swagger-ui.js

const express = require('express')
const pathToSwaggerUi = require('swagger-ui-dist').absolutePath()
const app = express()

// this is will load swagger ui
app.use(express.static(pathToSwaggerUi))

// this will serve your swagger.json file using express
app.use(express.static(`${__dirname}`))

// use port of your choice
app.listen(5000)

Install dependencies as npm install express and npm install swagger-ui-dist
Run the express application using the command node swagger-ui.js
Open browser and hit http://localhost:5000, this will load swagger ui with default URL as https://petstore.swagger.io/v2/swagger.json
Now replace the default URL mentioned above with http://localhost:5000/swagger.json and click on the Explore button, this will load swagger specification from a local JSON file

You can use folder name, JSON file name, static public folder to serve swagger.json, port to serve as per your convenience

sganabis · Answer 11 · 2021-04-18T08:49:40.160

This is not an answer just little update for paragbaxi's answer, so please upvote original answer instead this

paragbaxi's solution works like a charm in 2021

here is entire index.html for latest openapi=3.0.2:

<!-- HTML for static distribution bundle build -->
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8">
    <title>Swagger UI</title>
    <link rel="stylesheet" type="text/css" href="./swagger-ui.css" />
    <link rel="icon" type="image/png" href="./favicon-32x32.png" sizes="32x32" />
    <link rel="icon" type="image/png" href="./favicon-16x16.png" sizes="16x16" />
    <style>
      html
      {
        box-sizing: border-box;
        overflow: -moz-scrollbars-vertical;
        overflow-y: scroll;
      }

      *,
      *:before,
      *:after
      {
        box-sizing: inherit;
      }

      body
      {
        margin:0;
        background: #fafafa;
      }
    </style>
  </head>

  <body>
    <div id="swagger-ui"></div>
    <script src='spec.js' type="text/javascript"></script>
    <script src="./swagger-ui-bundle.js" charset="UTF-8"> </script>
    <script src="./swagger-ui-standalone-preset.js" charset="UTF-8"> </script>
    <script>
    window.onload = function() {
      // Begin Swagger UI call region
      const ui = SwaggerUIBundle({
        spec: spec,
        dom_id: '#swagger-ui',
        deepLinking: true,
        presets: [
          SwaggerUIBundle.presets.apis,
          SwaggerUIStandalonePreset
        ],
        plugins: [
          SwaggerUIBundle.plugins.DownloadUrl
        ],
        layout: "StandaloneLayout"
      });
      // End Swagger UI call region

      window.ui = ui;
    };
  </script>
  </body>
</html>

This is not an answer. Simply stating someone´s answer is still valid does not qualify a post as an aswer. Please remove and repost it as comment if needed, — GuedesBF, Apr 16 '21 at 16:48
You're absolutely right. this is not answer. Unfortunately I have not enough reputation to make comments. The reason why I've posted this is that the paragbaxi's code differs from that we have in last (2021) layout of `index.html`. And I've spend some time to figure out what is where should be changed. I wanted to help anyone who faced the same. If you still think that this should be deleted and posted as comment, could you please publish my code as comment and I will delete mine. (there is no matter for me who posted a code) — sganabis, Apr 18 '21 at 08:43

score 1 · Answer 12 · answered May 15 '17 at 16:43

My environment,
Firefox 45.9 , Windows 7
swagger-ui ie 3.x

I did the unzip and the petstore comes up fine in a Firefox tab. I then opened a new Firefox tab and went to File > Open File and opened my swagger.json file. The file comes up clean, ie as a file.

I then copied the 'file location' from Firefox ( ie the URL location eg: file:///D:/My%20Applications/Swagger/swagger-ui-master/dist/MySwagger.json ).

I then went back to the swagger UI tab and pasted the file location text into the swagger UI explore window and my swagger came up clean.

Hope this helps.

rob74 · Answer 13 · 2022-03-23T15:11:41.210

There is also an official Docker image with Swagger UI, so if you use Docker, this is probably the easiest way to get it to run locally.

Image On DockerHub (documentation links broken): https://hub.docker.com/r/swaggerapi/swagger-ui

Documentation on GitHub: https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/installation.md#docker

If you use docker-compose, you can adapt the following example config:

swagger:
  image: swaggerapi/swagger-ui
  environment:
    - "SWAGGER_JSON=/app/docs/[name of your OpenAPI file]"
  volumes:
    - "./[relative path of your OpenAPI file]:/app/docs"
  ports:
    - "[port you want to assign to the container]:8080"

(Yes, I know this is answer #17 at the time of this writing, but no previous answer has mentioned this Docker image)

If you just directly mount your json file to `/app/swagger.json` in your volumes like `./my-json-file.json:/app/swagger.json` then you don't need the environment. sauce: https://github.com/swagger-api/swagger-ui/blob/master/Dockerfile — ssi-anik, Mar 22 '22 at 18:09

score 0 · Answer 14 · answered Jul 23 '15 at 15:10

Instead of opening swagger ui as a file - you put into browser file:///D:/swagger-ui/dist/index.html you can: create iis virtual directory which enables browsing and points to D:/swagger-ui

open mmc, add iis services, expand Default Web Site add virtual directory, put alias: swagger-ui, physical path:(your path...) D:/swagger-ui
in mmc in the middle pane double click on "directory browsing"
in mmc in the right pane click "enable"
after that in browser put url to open your local swagger-ui http://localhost/swagger-ui/dist/
now you can use ../my.json if you copied file into dist folder or you can created separate forlder for samples, say D:/swagger-ui/samples and use ../samples/my.json or http://localhost/swagger-ui/samples/my.json

score 0 · Answer 15 · answered Aug 31 '16 at 08:47

This is how I worked with local swagger JSON

Have tomcat running in local machine
Download Swagger UI application and unzip it into tomcat's /webapps/swagger folder
Drop local swagger json file inside /webapps/swagger folder of tomcat
Start up tomcat (/bin/sh startup.sh)
Open a browser and navigate to http://localhost:8080/swagger/
type your swagger json file in the Swagger Explore test box and this should render the APIs.

Hope this works for you

score 0 · Answer 16 · answered Jun 04 '18 at 05:14

With Firefox, I:

Downloaded and unpacked a version of Swagger.IO to C:\Swagger\
Created a folder called Definitions in C:\Swagger\dist
Copied my swagger.json definition file there, and
Entered "Definitions/MyDef.swagger.json" in the Explore box

Be careful of your slash directions!!

It seems you can drill down in folder structure but not up, annoyingly.

score 0 · Answer 17 · answered Apr 20 '21 at 14:37

There is an option to use redoc for that.

it has cli to easily bundle spec and ReDoc into zero-dependency HTML file
responsive interface
and other pros So you can share only html file, without messing with webservers. But of course it need to be bundled again in case of spec changes.

score 0 · Answer 18 · answered Dec 08 '22 at 12:47

0

For spring boot application default url is: http://localhost:8080/swagger-ui/index.html

answered Dec 08 '22 at 12:47

Vipin

4,851
3
35
65

score -1 · Answer 19 · answered Feb 17 '17 at 17:14

Yet another option is to run swagger using docker, you can use this docker image:

https://hub.docker.com/r/madscientist/swagger-ui/

I made this ghetto little BASH script to kill running containers and rebuild, so basically each time you make a change to your spec and want to see it, just run the script. Make sure to put the name of your application in the APP_NAME variable

#!/bin/bash

# Replace my_app with your application name
APP_NAME="my_app"

# Clean up old containers and images
old_containers=$(docker ps -a | grep $APP_NAME | awk '{ print $1 }')
old_images=$(docker images | grep $APP_NAME | awk '{ print $3 }')

if [[ $old_containers ]];
    then
        echo "Stopping old containers: $old_containers"
        docker stop $old_containers
        echo "Removing old containers: $old_containers"
        docker rm $old_containers
fi

if [[ $old_images ]];
    then
        echo "Removing stale images"
        docker rmi $old_images
fi

# Create new image
echo "Creating new image for $APP_NAME"
docker build . -t $APP_NAME

# Run container
echo "Running container with image $APP_NAME"
docker run -d --name $APP_NAME -p 8888:8888 $APP_NAME
echo "Check out your swaggery goodness here:

http://localhost:8888/swagger-ui/?url=http://localhost:8888/swagger-ui/swagger.yaml"

How to open local files in Swagger-UI

19 Answers19

Create spec.js file containing Swagger JSON

Modify Swagger UI index.html

Include spec.js

Add spec parameter

Linked