tz-okapi 0.2.10

Requirements

• Python3.4

用于从requirements.txt开发安装需求。

pip install -r requirements.txt

Installation

sudo pip3 install tz-okapi

从源安装：

python setup.py install

从软件包安装：

pip install wheel
pip install tz_okapi-*.whl

在windows上，您可以将python添加到路径：

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

Usage

okapi

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/

[base]file=notebook-api.rstoutput=docs/apiurl=http://www.mynotebook/cache=1templates=docs/api/templatesverbosity=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

还不够吗？继续阅读…

Motivation

我们花了很长时间寻找一个工具来为 我们的项目。我们试过Apiary，我们试过 Swagger和越来越多的工具，但没有一个让我们满意。

我们需要的工具是：

• dry.我们懒得重复我们自己。重复是犯许多错误的一种方式。
• kiss.团队中的每个成员都应该能够在不知道某些内容的情况下编辑它 特殊的语法或规则。如此愚蠢简单。
• 可更改。这意味着，此人在数小时后不会编辑文档 API的每一个小变化。
• 可读原始格式。
• 可用于non-rest api（当然，也可用于restapi）。
• testable.不包含在测试中的文档很难维护。

Specification

.. code:: headers

  [HEADER_NAME: HEADER_VALUE]
  ...

.. code:: request

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

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

    [
    > tests
    > ..
    ]

{NAME:VALUE}

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