版权声明:本文为博主原创文章,未经博主允许不得转载。 https://blog.csdn.net/dqchouyang/article/details/80192593
一个项目,不仅仅要有详细的注释,还要有文档说明,这是必不可少的,尤其是写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文档了,如果想在样式上做调整,请自行找前端处理,不赘述。