Activity 4d (optional): View a *local* OpenAPI file in Swagger UI
I'm giving an API documentation workshop in Los Angeles, California, on January 23, 2020. Check it out on EventBrite and register today to receive a $100 early bird discount.
Activity 4d: View local OpenAPI file in Swagger UI
In order to view a local OpenAPI file (rather than an OpenAPI file hosted on a web server), you’ll need to run an HTTP server on your computer. This is because CORS (cross-origin resource sharing) security restrictions in Chrome will block Swagger UI from running. Swagger UI needs to load on a web server to fulfill the security requirements.
You can create a local web server running on your computer through Python’s SimpleHTTPServer module. Mac has a system version of Python installed by default, but Windows computers will need to install Python.
Windows: Run the Python simple HTTP server
-
Download and install Python 3x.
When you install Python, be sure to select the check box that says “Add Python 3.7 to PATH.” This check box isn’t selected by default. If you don’t select it, your command prompt won’t recognize the word “python”.
Add Python 3.7 to PATH - After installing Python, close your command prompt and reopen it.
-
In your command prompt, browse to the Swagger UI
dist
directory.To browse in the Windows command prompt, type
cd <folder name>
to move into the folder. Typecd ..
to move up a directory. Typedir
to see a list of the current directory’s contents.If you’re having trouble locating the
dist
directory in the command prompt, try this trick: typecd
, press the spacebar, and then drag thedist
folder directly into the command prompt. The path will be printed automatically. -
After you’ve navigated into the
dist
folder, launch the server:python3 -m http.server
If this command doesn’t work, try it without the 3:
python -m http.server
The server starts:
Serving HTTP on 0.0.0.0 port 8000 (http://0.0.0.0:8000/) ...
(If your Command Prompt doesn’t recognize
python
, then you probably need to add Python to your PATH. Instructions for doing that are outside the scope of this tutorial.) -
Copy the
http://0.0.0.0:8000/
path and paste it into your address bar. This address lets you view the local web server.By default, web servers default to the
index.html
file in the directory, so it will show the Swagger UI file automatically. If the browser doesn’t direct toindex.html
, add it manually:http://0.0.0.0:8000//index.html
.To stop the server, press Ctrl+C in your command prompt. If you closed your Command Prompt before stopping the service, type
ps
, find the process ID, then typekill -9 <process ID>
.
Mac: Run the Python simple HTTP server
-
In your terminal, browse to the Swagger UI
dist
directory.To browse in your terminal, type
cd <folder name>
to move into the folder. Typecd ..
to move up a directory. Typels
to see a list of the current directory’s contents.If you’re having trouble locating the
dist
directory in the command prompt, try this trick: typecd
, press the spacebar, and then drag thedist
folder directly into the command prompt. The path will be printed automatically. -
Since Mac already has Python, you can just run the following in your terminal to launch simple server:
python -m http.server
If this command doesn’t work, try it with the 3 in case you already have Python3 installed:
python3 -m http.server
The server starts:
Serving HTTP on 0.0.0.0 port 8000 (http://0.0.0.0:8000/) ...
-
Copy the
http://0.0.0.0:8000/
path and paste it into your address bar. This address lets you view the local web server.By default, web servers default to the
index.html
file in the directory, so it will show the Swagger UI file automatically. If the browser doesn’t direct toindex.html
, add it manually:http://0.0.0.0:8000//index.html
.To stop the server, press Ctrl+C in your command prompt. If you closed your Command Prompt before stopping the service, type
ps
, find the process ID, then typekill -9 <process ID>
.
For more details on using the Python simple server, see How do you set up a local testing server? for more details.
Customize the OpenAPI file
By default, SwaggerUI has the Petstore OpenAPI document configured in the url
parameter in the index.html
file. You need to swap in your local file instead.
-
Download the following OpenAPI document (right-click the link and save the YAML file to your desktop.): https://idratherbewriting.com/learnapidoc/docs/rest_api_specifications/openapi_openweathermap.yml
-
Drag your OpenAPI specification file,
openapi_openweathermap.yml
, into thedist
folder. Your file structure should look as follows:├── dist │ ├── favicon-16x16.png │ ├── favicon-32x32.png │ ├── index.html │ ├── oauth2-redirect.html │ ├── swagger-ui-bundle.js │ ├── swagger-ui-bundle.js.map │ ├── swagger-ui-standalone-preset.js │ ├── swagger-ui-standalone-preset.js.map │ ├── swagger-ui.css │ ├── swagger-ui.css.map │ ├── swagger-ui.js │ ├── swagger-ui.js.map │ ├── swagger30.yml │ └── openapi_openweathermap.yml
- Inside your
dist
folder, openindex.html
in a text editor such as Sublime Text. -
Look for the following code:
url: "http://petstore.swagger.io/v2/swagger.json",
-
Change the
url
value fromhttp://petstore.swagger.io/v2/swagger.json
to a relative path to your YAML file, and then save the file. For example:url: "openapi_openweathermap.yml",
-
View the
index.html
file locally in your browser using the Python simple server. For example, go tohttp://0.0.0.0:8000/
orhttp://0.0.0.0:8000/index.html
.If you go to the file path, such as
file:///Users/tomjoht/Downloads/dist/index.html
, you’ll see a message that says “Failed to load API definition” note in the JavaScript Console that says “URL scheme must be “http” or “https” for CORS request.” The SimpleServer simulates this http or https. - To stop the Python simpler server, press Ctrl+C in your terminal or command prompt.
25/150 pages complete. Only 125 more pages to go.
Want to buy me lunch? Click the Donate button below to donate any amount through Paypal.