项目API文档--markdown

一个项目，不仅仅要有详细的注释，还要有文档说明，这是必不可少的，尤其是写API，一定要有详细的接口文档。不废话了。

包名

Markdown==2.6.6

python 代码（这里不需要我做说明了把，应该都看的懂）

import markdown
from django.shortcuts import render, render_to_response
from project.settings import BASE_DIR


def help_doc(request, doc=None):
    if not doc:
        doc = 'api.md'
    doc_path = BASE_DIR + "/docs/" + doc
    md = markdown.Markdown(extensions=[
                               'markdown.extensions.extra',
                               'markdown.extensions.toc',
                               'markdown.extensions.codehilite'
                           ],
                           extension_configs={'permalink': True},
                           output_format='html')
    content = ''.join(file(doc_path, 'r').readlines())
    doc = md.convert(content)
    return render_to_response('api.html', context={'toc': md.toc, 'doc': doc})

api.html文件

<html style="background-color: #D2E9FF">
    <head>
        <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
        <title>RDS API</title>
        <style>
            .ztree li a.curSelectedNode {
                padding-top: 0px;
                background-color: #FFE6B0;
                color: black;
                height: 16px;
                border: 1px #FFB951 solid;
                opacity: 0.8;
            }
            .ztree{
                overflow: auto;
                height:100%;
                min-height: 200px;
                top: 0px;
            }
        </style>
    </head>
    <body style="">
        <div>
            <div style="width:30%;">
                <ul id="tree" class="ztree" style="width: 260px; overflow: auto; position: fixed; z-index: 2147483647; border: 0px none; left: 0px; bottom: 0px;">
                    {{ toc | safe }}
                </ul>
            </div>
            <div id="readme" style="width:70%;margin-left:25%;">
                <article class="markdown-body">
                    {{ doc | safe }}
                </article>
            </div>
        </div>
    <script type="text/javascript">
        $(document).ready(function(){
            $('#tree').ztree_toc({
                is_auto_number:false,
                documment_selector:'.markdown-body',
                is_expand_all: true
            });
        });
    </script>
    </body>
</html>

api.md 文档（格式不多说了，剩下的东西自己写了）

***
#### API名称：获取oauth2认证token（所有API将采用这种认证方式）

请求参数
<table border="1px" align="center" bordercolor="black" width="100%" height="100px">
    <tr align="center">
        <td>字段</td>
        <td>类型</td>
        <td>是否必选</td>
        <td>可为空</td>
        <td>默认值</td>
        <td>说明</td>
        <td>示例</td>
    </tr>
    <tr align="center">
        <td>grant_type</td>
        <td>string</td>
        <td>Y</td>
        <td>N</td>
        <td></td>
        <td>授权类型</td>
        <td>"password"</td>
    </tr>
    <tr align="center">
        <td>username</td>
        <td>string</td>
        <td>Y</td>
        <td>N</td>
        <td></td>
        <td>用户名</td>
        <td>"user1"</td>
    </tr>
    <tr align="center">
        <td>password</td>
        <td>string</td>
        <td>Y</td>
        <td>N</td>
        <td></td>
        <td>用户密码</td>
        <td>"1"</td>
    </tr>
    <tr align="center">
        <td>client_id</td>
        <td>string</td>
        <td>Y</td>
        <td>N</td>
        <td></td>
        <td>应用的id 跟管理员索要</td>
        <td>"KxlvQ2J8yRfYJXO9iSd2ugGUpamDZf0tS0B40HrI"</td>
    </tr>
    <tr align="center">
        <td>client_secret</td>
        <td>string</td>
        <td>Y</td>
        <td>N</td>
        <td></td>
        <td>应用密钥 跟管理员索要</td>
        <td>"UxkZHyXR31TpTvIRUGHYAiyJtxyAFKB4u
        koUvi3RnYZ8t5ceSelzN2n89hEvtYte4P0qGa0
        oRDiaBc5siJnERUJto8RbfR0VFl2ZtZ42U9oLT
        rfODdjjq8mmBXDZRGoe"</td>
    </tr>
</table>

返回结果

{
    "text": {
            "access_token": "2cbwATnNLIm2DkIqZtYX7I9OyJkqVB", 
            "token_type": "Bearer", 
            "expires_in": 604800,   # 7 days
            "refresh_token": "moLhUYln2NldVb7n7XxSmkgVEzpYVi", 
            "scope": "read write groups"
    },
    "status_code": 200,
}

所以根据上面的三个文件，就能构建一个简易的API文档了，如果想在样式上做调整，请自行找前端处理，不赘述。

项目API文档--markdown

猜你喜欢