项目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 APItitle>
        <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_typetd>
        <td>stringtd>
        <td>Ytd>
        <td>Ntd>
        <td>td>
        <td>授权类型td>
        <td>"password"td>
    tr>
    <tr align="center">
        <td>usernametd>
        <td>stringtd>
        <td>Ytd>
        <td>Ntd>
        <td>td>
        <td>用户名td>
        <td>"user1"td>
    tr>
    <tr align="center">
        <td>passwordtd>
        <td>stringtd>
        <td>Ytd>
        <td>Ntd>
        <td>td>
        <td>用户密码td>
        <td>"1"td>
    tr>
    <tr align="center">
        <td>client_idtd>
        <td>stringtd>
        <td>Ytd>
        <td>Ntd>
        <td>td>
        <td>应用的id 跟管理员索要td>
        <td>"KxlvQ2J8yRfYJXO9iSd2ugGUpamDZf0tS0B40HrI"td>
    tr>
    <tr align="center">
        <td>client_secrettd>
        <td>stringtd>
        <td>Ytd>
        <td>Ntd>
        <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文档了,如果想在样式上做调整,请自行找前端处理,不赘述。

你可能感兴趣的:(文档)