Skip to main content

A restful api document builder

Project description

eave

A Restful Api Document Builder


Installation

pip install eave

Requirements

  • Python >= 3.4

Basic Usage

# import components of eave
from eave import Doc, Note, Api, UP, QP, BP

# or you can import all
from eave import *


# startup a new doc
doc = Doc(title='My Api Document', host='www.myapi.com')

# add description for the doc
doc.description = """
the content of description is **markdown** format
1. one point
2. two point
3. three point
"""

# add a note into the doc
doc.add_note(
    title="note title",
    content="the content of note is also **markdown** format"
)

# add a get api into the doc
doc.add_api(
    title='Get all orders of shop',
    uri='/shop/<id>/orders/',
    method='GET',
    description='Get all orders of shop, shop admin login required',
    uri_params=[
        UP(name='id', description='the id of shop')
    ],
    query_params=[
        QP(name='page', type='integer', default=1),
        QP(name='page_size', type='integer', default=10),
    ],
    response_example="""
{
    "page": 1,
    "page_size": 10,
    "data": [
        {
          "order_id": "0021",
          "order_price": "120.00",
          "order_name": "xxx1",
        }
    ]
}
"""
)

# add a post api into the doc
doc.add_api(
    title='Create a product',
    uri='/products/',
    method='POST',
    body_params=[
        BP(name='name', required=True),
        BP(name='category', example='food'),
        BP(name='price', type='float', default=0),
    ],
    content_types=['application/json'],
    body_example="""
{
    "name": "Sprite 250ml",
    "category": "food",
    "price": 3.5
}
""",
    tips="""some `tips` for this api, also **markdown** format"""
)

# build the document to html
doc.build('best.html')

demo

Advanced Usage

# export to json
json_data = doc.to_json()

# create doc by json
doc2 = Doc(json_data)
doc2.title = 'My Second Api Document'

# build by chinese language
doc2.build('best2.html', language='zh')

# export to yaml
yaml_data = doc.to_yaml()
doc3 = Doc(yaml_data)
doc3.build('best3.html')

# read from raml
from eave.utils import raml2eave
doc = raml2eave('example.raml')
doc.build('example.html', 'zh')

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

eave-0.0.11.tar.gz (216.4 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page