wiki:ApiDocHowto
Last modified 18 months ago Last modified on 11/06/12 16:01:21

API Documentation Framework

Katello uses apipie-rails gem for the documentation of it's API.

This tool provides us:

  • DSL for describing the API (entry points, params, examples, error codes)
  • Interface to the documentation through the Katello API (in HTML and JSON format)
  • Static pages usable on Web or in Wiki
  • Validations of the parameters when running in special mode
  • Auto-generated API description from routes and system tests
  • Auto-generated examples from system tests

Writing documentation

The documentation is written using simple DSL. See sample documentation for EnvironmentsController for inspiration. It's set up to use Markdown as the markup language. You can browse the documentation directly under /apidoc path in your Katello instance.

In development mode, it reloads the documentation at each refresh, so that you can see directly the changes made in the code.

Adding .json to the documentation path, you can see the JSON representation of the documentation.

Production mode

It's not good practice to introduce documentation dependencies in production mode. Therefore there is a support for generating cache for the documentation files. This can be then used instead of generating the HTML while running the server. Thanks to this we have no dependencies to Markdown rendering engine in production.

You can generate the cache by running:

rake apipie:cache

Static pages

The documentation is not tied only to the running Katello instance. It can be transferred to static html pages looking exactly the same like the online version. The command for that is:

rake apipie:static

The static files are generated under doc/apidoc prefix:

  • doc/apidoc.html - entry point for the multi-page version
  • doc/apidoc-onepage.html - one-page version using bootstrap css
  • doc/apidoc-wiki.html - html suitable to insert into wiki (no css needed)

Automation with routes and system-tests

Part of documentation is already available in other artifacts and this tool helps extracting this information:

  • info about available paths can be extracted form routes.rb file using the following:
    rake apipie:update_from_routes
    
  • list of params, exit codes from system tests: turned on when running server with:
    APIPIE_RECORD=params RAILS_RELATIVE_URL_ROOT=/katello rails s thin -e production
    
    after running complete system tests (or another commands using Katello API), the data recoded are used to update the actions that have no docs at all or were generated with this tool before (presence of the disclaimer comment above the documentation tells it.
  • examples from system tests: Generating examples is turned on by running:
    APIPIE_RECORD=examples RAILS_RELATIVE_URL_ROOT=/katello rails s thin -e production
    
    the examples are saved into doc/apipie_examples.yml. You can specify what example to use by setting show_in_doc: 1 to the example (the number says it's order).

It's good idea to replace hostname of the machine you're running the tests from to more general hostname by running e.g.:

sed -i "s/$(hostname)/katello.example.com/g" doc/apipie_examples.yml

To generated both auto-params and examples run

APIPIE_RECORD=all RAILS_RELATIVE_URL_ROOT=/katello rails s thin -e production

Current development

To start working on the documentation it's needed just run bundle install to get the needed gems. After running server in development bode the documentation is available under /apidoc path.

Important note: Anytime you edit a description of some action, please remove the disclaimer stating it was auto-generated. Otherwise you risk it will be overwritten by running auto-documentation again.

Documentation efforts

Current documentation efforts are tracked here.