Skip to main content

Okapi is a simple tool to create documentation for your API and cover it with tests. It is based on reStructuredText format and very easy to learn.

Project description


To have API documentation OK.

Okapi is a simple tool to create documentation for your API and cover it with tests. It is based on reStructuredText format and very easy to learn.



  • Python 3.4

For developing install requirements from requirements.txt.

pip install -r requirements.txt


sudo pip3 install tz-okapi

Install from sources:

python install

Install from package:

pip install wheel
pip install tz_okapi-*.whl

On Windows you might add Python to paths:

setx path "%path%;C:\Python34;C:\Python34\Scripts;"



    okapi [<in> -cdo <out> --url=<url> --config=<config> --headers=<headers> -v <verbosity> --prototype]

    -c                      Enable persistent cache for responses.
    -d                      Allow debug mode.
    -o <out>                Output directory
    -v <verbosity>          Verbosity level [default: 2]
                                0 - no output
                                1 - summary
                                2 - failed tests
                                3 - all

    --url=<url>             URL against the requests are made
    --headers=<headers>     Custom headers sent to API, not visible in doc.
                            (Comma separated).
    --config=<config>       Config file. [default: okapi.cfg]
    --prototype             Run in prototype mode (no requests are made).

    okapi notebook.rst -o index.html --url=

Example configuration file

file = notebook-api.rst
output = docs/api
url = http://www.mynotebook/
cache = 1
templates = docs/api/templates
verbosity = 2


Notebook API documentation

Notebook is a project to create and read notes.

In every request, it should be sent this headers:

.. code:: headers

  Accept-Type: application/json
  Accept-Language: en,fr

Create new note

To create new note use this POST method. Note can be created
only with authenticated user.

.. code:: request

  POST /api/note/create/
  Authentication: johnsmith:topsecretpass

    "title": "My Note Title",
    "text": "Very long text..."

  > status_code == 201
  > 'id' in json()

If user is not successfully authenticated, status code ``401``
is returned:

.. code:: request

  POST /api/note/create/

  > status_code == 401

Get note detail

To get note detail, you have to provide its ``id``.

For example:

.. code:: request

  GET /api/note/{id:1}/

  > status_code == 200
  > 'title' in json()
  > 'text' in json()

Get notes list

To get all notes use this request:

.. code:: request

  GET /api/notes/

  > status_code == 200

It is possible to filter by creation date:

.. code:: request

  GET /api/notes/?date=2015-01-01

  > status_code == 200

Not enough? Continue in reading…


We were long time looking for a tool to create documentation for APIs of our projects. We tried Apiary, we tried Swagger and more and more tools, but none has satisfied us.

We needed tool, which would be:

  • DRY. We are lazy to repeat our selves. Repeating is a way do many mistakes.
  • KISS. Every member of team should be able to edit it without knowing some special syntax or rules. So super stupid simple.
  • Changeable. It means, that man wouldn’t edit documentation for hours after every small change in API.
  • Readable in raw format.
  • Usable for non-REST APIs (but for REST API, too, of course).
  • Testable. Documentation not covered with tests is hard to maintance.



Block used at the beginning of document to set common headers sent with request and disabled headers hidden from response. It should be used only once.

.. code:: headers



Block to describe API request. It has four parts:

  1. method and url (required)
  2. headers (optional)
  3. payload (optional)
  4. tests (recommended)
.. code:: request


    [{ ... json payload ... }]

    > tests
    > ..


URL cannot contain any space. Use encoded strings (%20 or +).

URLs can be with described params:




Change log

Release 0.2.10 (2015/09/24)

  • Disable redirects in API requests.

Release 0.2.9 (2015/09/22)

  • Fix UnicodeEncodeError during saving output.

Release 0.2.8 (2015/08/05)

  • #32 - Add MIT license
  • #33 - Fix bad interpreter error.

Release 0.2.7 (2015/08/04)

  • #12 - Fix path with using of include directive.

Release 0.2.6 (2015/08/04)

  • #30 - Added --prototype option to run in prototype mode. Prototype mode doesn’t execute any request, responses are faked.
  • #31 - Added automatically generated sidebar TOC to default template.

Release 0.2.5 (2015/07/27)

  • #27 - Added click on scroll functionality. Request and response are not scrollable by default, user has to click on them.
  • #26 - Fixed default template to show response status code even if response is empty.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Built Distribution

tz_okapi-0.2.10-py2.py3-none-any.whl (32.5 kB view hashes)

Uploaded 3 4

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page