接口文档的撰写与生成

方法一:用命令实现(较为麻烦)

1.apiDoc的安装

注意:在安装apiDoc之前,需要先安装Node.js,下载地址:https://nodejs.org/en/download/

• npm install apidoc -g
• 生成api的终端命令：apidoc -i 代码所在路径 -o 生成文件的路径
• eg:
• 根据提示,你需要建一个apidos.json
• 

 

• project的介绍写在单独的json文件中apidoc.json：

{
  "name": "project_name",
  "version": "0.1.0",
  "description": "who am i ,what i can do ",
  "title": " title of the html that generated by apiDoc",
  "sampleUrl" : "https://127.0.0.1:8000"
}

 

具体api的书写模版

"""

@api {methods} url description

@apiName unique_name

@apiGroup group

 

@apiParam {type} field description

 

@apiSuccessExample {json} Success-Response:

HTTP/1.1 200 OK

   {

    "errno":200,

    "errmsg":errmsg,

   }

@apiError errortype description.

@apiErrorExample {json} Error-Response:

 HTTP/1.1 200 OK

 {

    "errno":401

    "errmsg": "UserNotFound"

   }

"""

将api的书写模版粘到django项目的views.py中,再次执行生成api的终端命令

 此时去查看项目结构

 

刷新网页

 方法二:非命令式(较为简单)

1.创建一个新的项目

 2.将前两个文件复制粘贴到项目的根目录下

3.运行apidoc_init.py

 

4.执行生成api的终端命令

 此时会发现在项目根目录下会多个apidoctest文件夹

将该文件夹展开,找到index.html,在浏览器中打开后,刷新页面即可