程序员既痛恨写文档,又痛恨别人不写文档

edX目前已经有不少可用的api接口了:EdX Platform APIs

edx自带的api都是用django-rest-framework写的。如果我们需要扩展edx的api,好比为手机端提供额外的接口,建议也使用django-rest-framework来写api,而不要从django那里开始写

我去年为edx的论坛模块写过api,供移动端使用,最近为了将edx打造为子系统,需要写站点级别的api

写api倒挺有趣,可为了将api提供给别人用,我们需要为api写文档,这是件无聊乏味且容易出错的工作(收集参数什么的)。能不能像python doc那样从代码里直接生成文档呢。答案就是django-rest-swagger

#django-rest-swagger是什么

An API documentation generator for Swagger UI and Django REST Framework

相关文档参考这里

#install django-rest-swagger for edX 为了在edx中安装django-rest-swagger,我们需要做以下工作

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
#git clone
git clone https://github.com/marcgibbons/django-rest-swagger.git
cd django-rest-swagger
#edx的django版本是1.4,django-rest-swagger要求>1.5,所以我们注释掉依赖
#vim setup.py,注释掉以下内容
#'django>=1.5',
#'djangorestframework>=2.3.8',

sudo su edxapp -s /bin/bash
source /edx/app/edxapp/edxapp_env
pip install ./django-rest-swagger

#配置 往/edx/app/edxapp/edx-platform/lms/urls.py添加: INSTALLED_APPS += ('rest_framework_swagger',)

/edx/app/edxapp/edx-platform/lms/env/aws.py添加:

1
2
3
patterns += (
    url(r'^docs/', include('rest_framework_swagger.urls')),
)

#使用 访问 http://127.0.0.1/docs 即可

#效果 api1

api2

展示接口参数,可以直接在这里与接口往来数据

api3

下边是我扩展的接口:

api4