Asciidoctor for documenting REST APIs


Since more than 30 years I have to write good documentation. On the university I used to write documents with TeX and LaTeX because of the high quality output. The more professional the output is, the more professional the content looks to the reader. LaTeX offers a lot of possibilities to style your document so the reading can be fun. But LaTeX isn’t that simple. In my current projects I searched for a documentation tool that is wide spread, free and simple. The answer was Asciidoctor for me.

Document structure

The task is to write an API documentation and produce a typical HTML and PDF document as the output. This kind of documentation should be well structured because it is not meant to read at once but to give detail information when the reader needs it.

Document header

At the beginning of the document you should place general information about the document like

  • title
  • author
  • date of creation

Here is my default header snippet:

= API documentation for ...
Bernd Kursawe <>


After the title (“API documentation for …”) the author information follows (Name <e-mail>). With “:toc:” you place a table-of-content at the beginning of the document. “:sectanchors:” sets anchors at every section and “:sectnums:” care about the numeration of the sections.


The reader should get an idea at the beginning of the document what it’s all about. Explain keywords and the goal of the API. This should be the first section. In Asciidoctor the only thing you need to do is define a new section on the top level (2 =):

== Introduction

This API is ...

A person is a human beeing with a first and a last name...


Defining standards is important for the whole documentation. According to the DRY[1. Don’t repeat yourself] principle you should define common uses of HTTP verbs and response codes at the beginning of the document. Here is an example:

HTTP verbs have the following default meanings:

.HTTP verbs


|======= |Verb |Default usage of HTTP verb |GET |Get some information. Select resources by path variables. Query parameters can be used for multiple search parameters. Sending a request body is not allowed. |POST |Create new resources or start jobs (not idempotent!). The data for the new resource is send in the request body. The new resource or some information about the job are given back in the response body. Don’t use query parameters. |PUT |Change a resource. To select the resource use path variables. The complete resource data has to be send in the request body and the changed data is returned in the response body. Don’t use query parameters. |DELETE |Delete a resource. The resource is identified by its id as a path variable. There should be no request body or any query parameters. A response body is not required. |======= Here are the meanings of most used HTTP response codes: .Default response codes


|======= |Code |Meaning |Description |Used with |200 |OK |Response code if everything went OK. |GET, PUT, DELETE |201 |CREATED |Successful created a new resource |CREATED |404 |NOT FOUND |The resource(s) is/are not found. |GET, PUT, DELETE |=======

Group endpoints

Try to group endpoints (RequestMappings) of the same resource. Use the resource as a section and describe the raison d’√™tre of the resource. Every endpoint should be described in its own subsection. List all endpoints in the same order (e.g. GET, POST, PUT, DELETE). Here is a simple example:

=== Person

Administers information about people.

==== Find all people



===== Response fields

The response body contains a list of <<person-data>>.

===== Example request / response



==== Find a single person



===== Path parameters


===== Response fields

The response body contains <<person-data>>.

===== Example request / response



===== Wrong id



==== Create a new person



===== Request fields


===== Response fields

The response body contains <<person-data>>.

===== Example request / response



==== Delete a person



===== Path parameters


===== Response fields


===== Example request / response



===== Wrong id



Data structures

Often you use the same resource (data structure) in several endpoints. This is boring for the reader and the document size becomes longer as necessary. So add a separate section at the end. Describe all common data structures like this:

== Data types

=== Person



Are there any alternatives to Asciidoctor? Of course, but here are some and the reasons I don’t use them:

  • Microsoft Word / LibreOffice: Although WYSIWYG-editors has a lot of advantages it has drawbacks producing HTML output. In HTML everything looks a little bit different to the layout in the editor and this is at least misleading.
    Another problem is the document format. It is not simple text but (proprietary) XML. When you want to use a versioning system like GIT it is difficult to see the differences between 2 versions in a structured format like XML.
  • LaTeX: Complicated to learn and slow processing. It offers amazing possibilities to format and style your document in PDF. But it has no advantages when used to produce HTML.
  • Markdown: A ‘cousin’ of Asciidoctor with lesser functionality but also usable for API documentation. It were my second choice.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.