tz-okapi 0.2.5

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

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.

---

Contents:

• Requirements

• Installation

• Usage

  • Example configuration file

• Example

• Motivation

• Specification

  • headers

  • request

  • url

---

Requirements

• Python 3.4

For developing install requirements from requirements.txt.

pip install -r requirements.txt

Installation

sudo pip3 install tz-okapi

Install from sources:

python setup.py 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;"

Usage

okapi

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

Options:
    -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]

Example:
    okapi notebook.rst -o index.html --url=http://www.notebook.com/

Example configuration file

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

Example

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…

Motivation

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.

Specification

headers

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

  [HEADER_NAME: HEADER_VALUE]
  ...

  [!HEADER_NAME]
  ...

request

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

    (GET|POST|PUT|PATCH|DELETE|OPTIONS|HEAD|TRACE|CONNECT) (URL) [HTTP_VERSION]
    [HEADER_NAME: HEADER_VALUE]
    ...

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

    [
    > tests
    > ..
    ]

url

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

URLs can be with described params:

{NAME:VALUE}

eg.:

/api/note/{typeId:1}/{noteId:3}/