Running Swagger UI to Verify Local OpenAPI/Swagger Documents

Featured image for sharing metadata for article

Something that's really handy for visualising OpenAPI, or older Swagger, documents is the Swagger UI project.

If you've got a publicly resolvable OpenAPI document available, you can use the Swagger UI found on, but in a lot of cases this isn't possible, especially as you'd need to get CORS settings correct.

Additionally, you may not want to be publishing your OpenAPI specs publicly, so need the option of running it locally.

There are a few options to running it, which I thought I'd document as I spent a while fighting this today.


The documentation on the project doesn't appear to work for me, as I'm receiving HTTP 403s when trying to read the contract. I've raised this patch to fix it upstream, which leads us to i.e. the following, for the domains.openapi.json contract:

docker run -p 80:8080 -e SWAGGER_JSON=domains.openapi.json -v $PWD/domains.openapi.json:/usr/share/nginx/html/domains.openapi.json swaggerapi/swagger-ui

Serving with our own HTTP server

Alternatively, we can use the built version of the HTML/CSS/JavaScript assets and serve them through a local HTTP server.

The built version of the package can be found either in the dist folder in the repo, or using the NPM package swagger-ui-dist.

For instance, if we download via NPM:

npm i swagger-ui-dist
cd ./node_modules/swagger-ui-dist
# we're now in the right directory for the following commands
cp /path/to/swagger.json .

NodeJS http-server

For example, we can use NodeJS' http-server package to serve the directory.

From the dist / swagger-ui-dist folder, we can run:

npx http-server --cors

Which will then serve the directory HTTP, allowing CORS requests, and we can point Swagger UI to the ./swagger.json file.


Python's inbuilt http.server module works in a pinch, too, which means from the dist / swagger-ui-dist folder, we can run:

python -m http.server

Which we can also use to point to the ./swagger.json file.

Written by Jamie Tanna's profile image Jamie Tanna on , and last updated on .

Content for this article is shared under the terms of the Creative Commons Attribution Non Commercial Share Alike 4.0 International, and code is shared under the Apache License 2.0.

#blogumentation #swagger #openapi #cors.

This post was filed under articles.

Interactions with this post

Interactions with this post

Below you can find the interactions that this page has had using WebMention.

Have you written a response to this post? Let me know the URL:

Do you not have a website set up with WebMention capabilities? You can use Comment Parade.