Workshop description

In the Documenting REST APIs workshop, we used a simple Weather API from Mashape to demonstrate how to use and create a REST API. In this course, we’ll explore various tools to publish information from the Mashape Weather API that we covered in the previous course. Some of the publishing approaches we’ll explore are the following:

  • Github wikis and Markdown
  • Swagger
  • API Blueprint
  • RAML
  • Jekyll and static site generators
  • Miredot
  • Help authoring tools such as Flare

With almost every one of these tools, you’ll deploy a sample file to publish content.

Regardless of the tool you choose, there are some common design patterns with API doc, such as the following:

  • Structure and templates
  • Website platforms
  • Abundant code examples
  • Single-click navigation
  • Interactive API explorers

The tools you choose depend partly on your requirements. If you have to account for translation, content re-use, versioning, authentication, or PDF output, these requirements impact your tool decisions.

Sponsored content


The first course, Documenting REST APIs workshop, is the recommended (but not required) prerequisite.

Required software

Note that your computer needs to be able to connect to a wifi network.


The workshop lasts 3 hours.