tz-okapi 0.2.10

需求

• Python 3.4

为了开发，请从requirements.txt安装需求。

pip install -r requirements.txt

安装

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;"

使用

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.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

还不够？继续阅读…

动机

我们长期以来一直在寻找一个工具来创建我们项目API的文档。我们尝试了Apiary，尝试了Swagger和越来越多的工具，但没有一个让我们满意。

我们需要一个工具，它应该是

• DRY（Don't Repeat Yourself）。我们不愿意重复自己。重复是犯许多错误的方式。

• KISS（Keep It Simple, Stupid）。团队中的每个成员都应该能够编辑它，而无需了解一些特殊的语法或规则。所以非常简单。

• 可变。这意味着，在API的每一次小变化之后，人们都不需要花几个小时来编辑文档。

• 以原始格式可读。

• 适用于非REST API（但当然也适用于REST API）。

• 可测试。未涵盖测试的文档难以维护。

规范

.. 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}/

发布 0.2.10 (2015/09/24)

• 禁用API请求中的重定向。

发布 0.2.9 (2015/09/22)

• 修复保存输出时的UnicodeEncodeError。

发布 0.2.8 (2015/08/05)

• #32 - 添加MIT许可证

• #33 - 修复错误的解释器错误。

发布 0.2.7 (2015/08/04)

• #12 - 修复使用include指令的路径。

发布 0.2.6 (2015/08/04)

• #30 - 添加了--prototype选项以在原型模式下运行。原型模式不执行任何请求，响应是伪造的。

• #31 - 将自动生成的侧边栏目录添加到默认模板中。

发布 0.2.5 (2015/07/27)

• #27 - 添加了点击滚动功能。默认情况下，请求和响应不可滚动，用户必须点击它们。

• #26 - 修复了默认模板，即使响应为空，也显示响应状态代码。