How to open local files in Swagger-UI
FileSwaggerSwagger UiSwagger 2.0File Problem Overview
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 tofile:///D:/swagger-ui/dist/index.html/my.json
-
file:///D:/swagger-ui/dist/my.json
leads tofile:///D:/swagger-ui/dist/index.html/file:///D:/swagger-ui/dist/my.json
File Solutions
Solution 1 - File
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"
Solution 2 - File
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",
Solution 3 - File
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
2. get swagger-editor with below command:
git clone https://github.com/swagger-api/swagger-editor.git
3. go into swagger-editor directory that is created now
cd swagger-editor
4. now get swagger-ui with below command:
git clone https://github.com/swagger-api/swagger-ui.git
5. now, copy your swagger file, I copied to below path:
./swagger-editor/api/swagger/swagger.json
6. all setup is done, run the swagger-edit with below commands
npm install
npm run build
npm start
7. 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.
Solution 4 - File
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
Solution 5 - File
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
Solution 6 - File
What works, is to enter a relative path or an absolute without the file://
-protocol:
../my.json
leads tofile:///D:/swagger-ui/dist/index.html/../my.json
and works/D:/swagger-ui/dist/my.json
leads tofile:///D:/swagger-ui/dist/my.json
and works
HINT
This answer works with Firefox on Win7. For Chrome-Browser, see comments below:
Solution 7 - File
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
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 caseswagger-ui.js
in the same newly created folder and copy and save the following content in the fileswagger-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
andnpm 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
Solution 8 - File
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
Solution 9 - File
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
}
Solution 10 - File
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.
Solution 11 - File
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)
Solution 12 - File
Solution 13 - File
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
Solution 14 - File
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
Solution 15 - File
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.
Solution 16 - File
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>
Solution 17 - File
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.
Solution 18 - File
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"