Workshop description

Whereas the Documenting REST APIs and Publishing REST API Documentation workshops focused specifically on REST APIs, this workshop focuses on Java APIs.

Java APIs belong to a cateogory of APIs that are sometimes referred to as platform APIs. (Others might call them library APIs, class APIs, or native APIs.) The basic difference is that rather than using HTTP protocol to make and receive requests (as you do with REST APIs), you add a library of classes or functions to your code and then call the classes or functions in your code. There is no exchange of information across HTTP protocols.

To document a Java API, you need some understanding of Java. Although you don’t have to be a programmer, you need to know enough about Java to understand various terms and lingo. Some of the terms that are important to know include the following:

  • Class: similar to a blueprint or template
  • Object: an instance of a class
  • Methods: what the object/class can do
  • Fields: variables in the object/class
  • Constructor: a method to create an object for a class
  • Package: a folder that groups classes
  • Access modifier (e.g, public): the scope at which a thing can be accessed
  • Interface: a skeleton class with empty methods (used for standardizing)
  • Enum: a data type offering predefined constants
  • Subclass: a class that inherits the fields + methods of another class
  • JAR file: a zip-like file containing Java classes
  • WAR file: a compiled Java web application to be deployed on a server
  • Doclet: what parses the Javadoc tags and produces the Javadoc output

You don’t need to know Java before you take this workshop. However, if you’re new to Java, the workshop will probably introduce a lot of new terms and concepts that you can later study to understand more fully.

One difference with platform API documentation is that the reference documentation (but the other parts of the documentation) is usually created in the same files as the source code. Before each class or method, you add a “doc block” that describes the class or method.

The doc blocks follow a specific syntax that is highly structured. For example, you describe a parameter by using the @param tag followed by your description.

Java APIs are similar to C++ and C# APIs, but the syntax and tools differ somewhat. Some of the superficial differences with the C++ and C# platform APIs are noted in this workshop, but not in extensive detail.

For example, you will learn how to use Doxygen instead of Javadoc to generate API documentation. You will also see the difference in the doc block syntax and some terminology, but other differences will not be explored.

Required software

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


The workshop lasts 3 hours.

Stay current with the latest in tech comm
Keep current with the latest trends in technical communication by subscribing to the I'd Rather Be Writing newsletter. 4,500+ subscribers