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.
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.
Requirements
Python 3.4
For developing install requirements from requirements.txt.
pip install -r requirements.txtInstallation
sudo pip3 install tz-okapiInstall from sources:
python setup.py installInstall from package:
pip install wheel
pip install tz_okapi-*.whlOn 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 = 2Example
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 == 200Not 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:
method and url (required)
headers (optional)
payload (optional)
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}/
