Package: tz-okapi
okapiTo have API documentation OK.Okapi is a simple tool to createdocumentation for your APIandcover
it with tests. It is based onreStructuredTextformat and very easy to learn.Contents:okapiRequirementsInstallationUsageExample configuration fileExampleMotivationSpecificationheadersrequesturlChange logRelease 0.2.10 (2015/09/24)Release 0.2.9 (2015/09/22)Release 0.2.8 (2015/08/05)Release 0.2.7 (2015/08/04)Release 0.2.6 (2015/08/04)Release 0.2.5 (2015/07/27)RequirementsPython3.4For developing install requirements fromrequirements.txt.pipinstall-rrequirements.txtInstallationsudopip3installtz-okapiInstall from sources:pythonsetup.pyinstallInstall from package:pipinstallwheelpipinstalltz_okapi-*.whlOn Windows you might add Python to paths:setx path "%path%;C:\Python34;C:\Python34\Scripts;"Usageokapi

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

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]
    --prototype             Run in prototype mode (no requests are made).

Example:
    okapi notebook.rst -o index.html --url=http://www.notebook.com/Example configuration file[base]file=notebook-api.rstoutput=docs/apiurl=http://www.mynotebook/cache=1templates=docs/api/templatesverbosity=2ExampleNotebook API documentation==========================Notebook is a project to create and read notes.In every request, it should be sent this headers:..code::headersAccept-Type: application/json
  Accept-Language: en,frCreate new note---------------To create new note use this POST method. Note can be createdonly with authenticated user...code::requestPOST /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::requestPOST /api/note/create/

  > status_code == 401Get note detail---------------To get note detail, you have to provide its``id``.For example:..code::requestGET /api/note/{id:1}/

  > status_code == 200
  > 'title' in json()
  > 'text' in json()Get notes list--------------To get all notes use this request:..code::requestGET /api/notes/

  > status_code == 200It is possible to filter by creation date:..code::requestGET /api/notes/?date=2015-01-01

  > status_code == 200Not enough? Continue in reading…MotivationWe were long time looking for a tool to create documentation for APIs of
our projects. We triedApiary, we triedSwaggerand 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.Readablein raw format.Usable fornon-REST APIs(but for REST API, too, of course).Testable.Documentation not covered with tests is hard to maintance.SpecificationheadersBlock 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]
  ...requestBlock 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
    > ..
    ]urlURL cannot contain any space. Use encoded strings (%20or+).URLs can be with described params:{NAME:VALUE}eg.:/api/note/{typeId:1}/{noteId:3}/Change logRelease 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--prototypeoption 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 - Addedclick on scrollfunctionality. 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.