1. I'd Rather Be Writing
2. Learn API Doc

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. You can view details on EventBrite here.

Input needed: I'm currently conducting a survey about trends in developer documentation for 2020. If you write docs for developers, please take this survey. (You can view the ongoing results viewed here.)

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

1. 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”.

   

2. After installing Python, close your command prompt and reopen it.

3. 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. Type cd .. to move up a directory. Type dir 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: type cd, press the spacebar, and then drag the dist folder directly into the command prompt. The path will be printed automatically.

4. 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.)

5. 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 to index.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 type kill -9 <process ID>.

Mac: Run the Python simple HTTP server

1. In your terminal, browse to the Swagger UI dist directory.

   To browse in your terminal, type cd <folder name> to move into the folder. Type cd .. to move up a directory. Type ls 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: type cd, press the spacebar, and then drag the dist folder directly into the command prompt. The path will be printed automatically.

2. 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/) ...
   

3. 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 to index.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 type kill -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.

1. 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

2. Drag your OpenAPI specification file, openapi_openweathermap.yml, into the dist 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
   

3. Inside your dist folder, open index.html in a text editor such as Sublime Text.

4. Look for the following code:

   url: "http://petstore.swagger.io/v2/swagger.json",
   

5. Change the url value from http://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",
   

6. View the index.html file locally in your browser using the Python simple server. For example, go to http://0.0.0.0:8000/ or http://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.

7. To stop the Python simpler server, press Ctrl+C in your terminal or command prompt.