Search results

Activity 4c: Create a Swagger UI display

Keep current with the latest trends in technical communication by subscribing to the I'd Rather Be Writing newsletter. 5,000+ subscribers

Activity 4c: Create a Swagger UI display with an OpenAPI spec document

In this activity, you’ll create a Swagger UI display for an OpenAPI specification document. If you’re using one of the pre-built OpenAPI files, you can see a demo of what we’ll build here: OpenWeatherMap Swagger UI.

Demo of Swagger UI
Demo of Swagger UI rendering an OpenWeatherMap OpenAPI specification document

First, you’ll make sure you can view Swagger locally. Then you’ll switch the Petstore OpenAPI document URL with an OpenWeatherMap OpenAPI document URL.

  1. Go to the Swagger UI GitHub project.
  2. Click Clone or download, and then click Download ZIP. Download the files to a convenient location on your computer and extract the files.

    The only folder you’ll be working with in the downloaded zip is the dist folder (short for distribution). Everything else is used only if you’re recompiling the Swagger files, which is beyond the scope of this tutorial. If desired, you can drag the dist folder out of the swagger-ui-master folder so that it stands alone.

  3. In your Chrome browser, press Cmd+O (Mac) or Ctrl+O (Windows), browse to the dist folder, and select the index.html file,

    You should see the Petstore Swagger content. Now you’ll customize the OpenAPI spec file with another file.

  4. Inside your dist folder, open index.html in a text editor such as Sublime Text.
  5. Look for the following code:

    url: "http://petstore.swagger.io/v2/swagger.json",
    
  6. Change the url value to https://idratherbewriting.com/learnapidoc/docs/rest_api_specifications/openapi_openweathermap.yml and then save the file.

    For example:

    url: "https://idratherbewriting.com/learnapidoc/docs/rest_api_specifications/openapi_openweathermap.yml",
    
  7. Refresh the index.html file in your Chrome browser. The content should show the OpenWeatherMap API content instead of Swagger Petstore content.

    When you’re ready to publish your Swagger UI file, you just upload the dist folder (or whatever you want to call it) to a web server and go to the index.html file. For example, if you called your directory dist (leaving it unchanged), you would go to http://myserver.com/dist/.

    For more instructions in working with Swagger UI, see the Swagger.io docs.

10% Complete

10/150 pages complete. Only 140 more pages to go.



Donate?

Want to buy me lunch? Click the Donate button below to donate any amount through Paypal.