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
This question is related to
file
swagger
swagger-ui
swagger-2.0
Use the spec parameter.
Instructions below.
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"
},
...
}
}
This is a two-step like Ciara.
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";
}
Modify the SwaggerUi instance to include the spec
parameter:
window.swaggerUi = new SwaggerUi({
url: url,
spec: spec,
dom_id: "swagger-ui-container",
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"
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.
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
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
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.
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
}
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):
npm install -g http-server
http-server --cors
(CORS has to be enabled for this to work)http://localhost:8080/my.json
in input field and click "Explore"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
swagger.json
to the newly created folder.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)
npm install express
and npm install swagger-ui-dist
node swagger-ui.js
http://localhost/5000
, this will load swagger ui with default URL as https://petstore.swagger.io/v2/swagger.jsonhttp://localhost:5000/swagger.json
and click on the Explore button, this will load swagger specification from a local JSON fileYou can use folder name, JSON file name, static public folder to serve swagger.json
, port to serve as per your convenience
This is how I worked with local swagger JSON
Hope this works for you
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
I had that issue and here is much simpler solution:
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
With Firefox, I:
swagger.json
definition file there, andBe careful of your slash directions!!
It seems you can drill down in folder structure but not up, annoyingly.
Source: Stackoverflow.com