Workshop activities

The following are activities used in the live workshops.

Part I: Intro to API documentation

Slides: Intro to API documentation

Activity: Explore an API

Explore the basic sections in API reference documentation in these 2 weather APIs:

Activity: Make a curl request


curl --get --include '' -H 'X-Mashape-Key: EF3g83pKnzmshgoksF83V6JB6QyTp1cGrrdjsnczTkkYgYrp8p' -H 'Accept: application/json'


curl --get -k --include "" -H "X-Mashape-Key: EF3g83pKnzmshgoksF83V6JB6QyTp1cGrrdjsnczTkkYgYrp8p" -H "Accept: application/json"

Activity: Postman client

  1. Download Postman.
  2. Populate Postman from the Run in Postman button or from this link:

  3. Make requests in Postman.
  4. Generate code snippets in JavaScript (AJAX) from Postman.
  5. Create a Run in Postman button for your requests. In the Collections pane, click the < arrow to expand the pane and click Share.

Part II: OpenAPI and Swagger

Slides: OpenAPI and Swagger

Activity: OpenAPI with Stoplight

  1. Open v3 next Stoplight app. (You can also use the Desktop app)
  2. From main.oas, open the Code tab and paste in content for this 2.0 JSON Open API definition:
  3. Edit, explore Basics, Requests, Responses sections.
  4. In the Responses area, click Generate from JSON, paste in complex JSON snippet into the Responses area, then click Generate!

     "query": {
       "count": 1,
       "created": "6/14/2017 2:30:14 PM",
       "lang": "en-US",
       "results": {
         "channel": {
           "units": {
             "distance": "km",
             "pressure": "mb",
             "speed": "km/h",
             "temperature": "C"
           "title": "Yahoo! Weather - Singapore, South West, SG",
           "link": "*",
           "description": "Yahoo! Weather for Singapore, South West, SG",
           "language": "en-us",
           "lastBuildDate": "Wed, 14 Jun 2017 10:30 PM SGT",
           "ttl": 60,
           "location": {
             "city": "Singapore",
             "country": "Singapore",
             "region": "South West"
           "wind": {
             "chill": 81,
             "direction": 158,
             "speed": 0
           "atmosphere": {
             "humidity": 87,
             "pressure": 0,
             "rising": 0,
             "visibility": 0
           "astronomy": {
             "sunrise": "6:59 am",
             "sunset": "7:11 pm"
           "image": {
             "title": "Yahoo! Weather",
             "width": 142,
             "height": 18,
             "link": "",
             "url": ""
           "item": {
             "title": "Conditions for Singapore, South West, SG at 09:00 PM SGT",
             "lat": 1.33464,
             "long": 103.726471,
             "link": "*",
             "pubDate": "Wed, 14 Jun 2017 09:00 PM SGT",
             "condition": {
               "code": 33,
               "date": "Wed, 14 Jun 2017 09:00 PM SGT",
               "temp": 26,
               "text": "Mostly Clear"
             "forecast": [
                 "code": 4,
                 "date": "14 Jun 2017",
                 "day": "Wed",
                 "high": 28,
                 "low": 25,
                 "text": "Thunderstorms"
             "description": "<![CDATA[<img src=\"\"/>\n<BR />\n<b>Current Conditions:</b>\n<BR />Thunderstorms\n<BR />\n<BR />\n<b>Forecast:</b>\n<BR /> Fri - Thunderstorms. High: 30Low: 25\n<BR /> Sat - Thunderstorms. High: 28Low: 25\n<BR /> Sun - Thunderstorms. High: 28Low: 25\n<BR /> Mon - Thunderstorms. High: 28Low: 25\n<BR /> Tue - Thunderstorms. High: 28Low: 25\n<BR />\n<BR />\n<a href=\"*\">Full Forecast at Yahoo! Weather</a>\n<BR />\n<BR />\n(provided by <a href=\"\" >The Weather Channel</a>)\n<BR />\n]]>",
             "guid": "string"

Activity: Swagger Editor

  1. Paste this YAML file into Swagger Editor and make updates.
  2. Go to this SwaggerHub API. Observe Generate Client SDK options.

Activity: Swagger UI

  1. Download Swagger UI.
  2. Uncompress and pull out the dist folder.
  3. Save this file locally: into the dist folder.
  4. Reference openapi_weather.yml in place of the default url value.
  5. Open in Firefox.

Part III: Non-reference content in API docs

Slides: Non-reference content in API docs

Activity: GitHub workflow

  1. Create new repo and initialize with readme. Clone repo locally using git clone.
  2. Make update to readme file and push back into repo:
git add .
git commit -m "made update to readme"
git pull
git push
9% Complete

9/94 pages complete. Only 85 more pages to go...


If you would like to contribute back to say thank you for the API documentation course, click the Donate button below. Alternatively, to contribute content, such as a tutorial or a new section, contact me with your ideas. You can also submit a pull request in the GitHub repo to make your contribution. Even if you want to just fix a typo or add a sentence here and there, it's always welcome.

Get new posts delivered straight to your inbox.

Subscriber count: 4,285