Apidoc的安装与使用

Apidoc简介

apidoc是一款可以根据源代码中的注释直接自动生成api接口文档的工具。生成一个doc文件夹，包含了渲染的css，fonts等, python中注释的方法为

"""  
@apidoc  
"""

安装及应用

安装前，需要先更新到最新的node.js,  使用npm执行命令:

npm install apidoc -g

安装好后，在要生成接口文档的源码根目录下， 建立一个配置文档apidoc.json， 这个文档主要包含一些项目的描述信息，比如标题、简述、版本等，你也可以加入一些可选的配置项，比如页眉、页脚、模板等。
 ==ps： 如果未检测到apidoc.json， 导出文档会报错~==

{
    "name":                   "项目名称",   
    "version":                "版本",                
    "description":            "简述",
    "title":                  "浏览器标题",
    "url" :                   "api路径前缀，例：https://api.kafka.com",
    "apiSampleRequest"(选填): "导出的文档中每一个接口都会包含模拟接口请求的form表单(测试接口)",
    "header.title"(选填):     "页眉标题"，
    "header.filename"(选填):  "页眉文件名",
    "footer.title" (选填):    "页脚标题"，
    "footer.filename"(选填):  "页脚文件名"，
    "order"(选填):            "排序"
}

导出文档时, 在根目录执行命令即可

apidoc -i (要生成文档的文件) -o (文档生成目标文件中)

eg: apidoc -i qhd_convert_fields\models -o  .\apidoc

Python中apidoc注释参数

常规注释详解:

def Apidoc()
        """
        @api {请求类型}  路径(根路径)   接口标题,
        ----------eg:-------------
        @api {get, post} /test_consumer_button 测试kafka消费

        @apiVersion  版本号
        @apiName  接口名称
        @apiDescription 接口的描述
        @apiGroup 所属分组, 例如一个模块为一个分组,那模块下所有的接口分组都是同一个
        @apiPermission  允许访问该接口的角色名称(唯一)
        @apiSampleRequest  如果apidoc.json中有设置apiSampleRequest, 在接口注释中再写则意味着覆盖 ,
                    如果apidic.json中没有设置, 则给当前接口单独设置模拟接口
                    @apiSampleRequest off意为关闭当前接口测试功能

        请求参数: 固定格式
        @apiParam (所属组(有默认)) {字段类型}   字段名([选填],[=默认值])    字段描述
        ----------eg:-------------
        @apiParam             {String}     ip=10.1.254.107           有默认值且必填的IP字段 
        @apiParam             {Number}      [port=9092]              有默认值且选填的端口
        @apiParam             {String}      topic_name               必填项topic名
        
        
        请求体参数示例:固定格式
        @apiParamExample [{请求内容格式}] [请求示例标题]
                   example  请求示例详情(兼容多行)
         ----------eg:-------------
        @apiParamExample {json} Request-test:
            {
                'name': test_kafka,
                'IP': 127.0.0.1,
                'Port': 8868,
                'thread_num': 5,
            }
        
        接口成功返回参数: 固定格式
        @apiSuccess [(group)] [{type}] field [description]
        ----------eg:-------------
        @apiSuccess {bool}            msg             successful     # group默认值:Success200
        @apiSuccess (200) {bool}      msg             successful        
        @apiSuccess {Number}          self.age        回参为数值
        @apiSuccess {Object}          self.kafka_msg  回参为对象
        @apiSuccess {Object[]}        self            回参为数组

        返回成功示例
        @apiSuccessExample [{type}] [title]
                   example
         ----------eg:-------------
        @apiSuccessExample {json} Success-Response:
            {
                'msg': 'Connect successful',
                'age':self.age,
                'topic_list':  [
                    'real_timeStationTopic',
                    'unexpectedStationTopic']
            }
        """
        print('This is a demo')
        
        

完整示例:

def apidoc():
    """
    @api {get, post} /test_producer_button 测试kafka生产
    @apiVersion 1.0.0
    @apiName 测试kafka生产
    @apiDescription 测试传入的数据根据topic是否可以生产消息, 传入的数据需要手动填入
    @apiGroup Lty_kafka_gateway
    @apiSampleRequest off
    @apiParam {String}  ip=10.1.254.107        kafka的IP地址
    @apiParam {Number}  [port=9092]            kafka的端口
    @apiParam {String}  topic_name             主题名
    @apiParam {String}  [another]              其他的根据对应topic,在键入消息栏填入数据, 判
                                               断是否可以生产成功数据
    @apiParamExample {json} Request-Example:
        {
            "IP": 127.0.0.1,
            "Port": 8868,
            "topic_name": test_kafka,
            "line_id": 12,
            "gprs_id": 456,
        }

    @apiSuccess {bool}      msg                 successful
    @apiSuccess {Number}    age                 successful age
    @apiSuccess {Object}    self.kafka_msg      successful msg
    @apiSuccess {Object[]}  self                self msg

    @apiSuccessExample {json} Success-Response:
        {
        "msg": "Connect successful",
        "age":self.age,
        "kafka_msg":self.kafka_msg,
        "self":self,
        "topic_list":  [
            "real_timeStationTopic",
            "unexpectedStationTopic",
            "BusInspect_Topic",
            "ITS_Topic_ScheduingPlan"]
        }
    """

 

注释详解:

1、 @api

【必填字段】否则，apidoc会忽略该条注释

 

参数	必填	描述
method	yes	请求类型:DELETE, GET, POST, PUT, ...更多
path	yes	请求路径
title	no	接口标题

例：

"""
@api {get} /user/:id
@api {get, post} /test_consumer_button 测试kafka消费
"""

2、 @apiDefine

定义注释模块(类似于代码中定义一个常量)，对于一些通用可复用的注释模块(例如:接口错误响应模块),只需要在源代码中定义一次，便可以在其他注释模块中随便引用，最后在文档导出时会自动替换所引用的注释模块，定义之后您可以通过@apiUse来引入所定义的注释模块。(注:可以同时使用@apiVersion来定义注释模块的版本)

参数列表：

参数	必填	描述
name	yes	注释模块名称(唯一)，不同@apiVersion可以定义相同名称的注释模块
title	no	注释模块标题
description	no	注释模块详细描述(详细描述另起一行，可包含多行)

3、@apiDeprecated

标注一个接口已经被弃用

参数列表：

参数	必填	描述
text	yes	多行文字描述

例：

"""
@apiDeprecated  Why abandon
"""

4、@apiDescription

api接口的详细描述

参数列表：

参数	必填	描述
text	yes	多行文字描述

例：

"""
@api {get} /user/:id
@apiDescription 测试传入的数据根据topic是否可以生产消息
"""

5、@apiError

错误返回参数

参数列表：

参数	必填	描述
(group)	no	所有的参数都会通过这个参数进行分组，如果未设置，默认值为Error 4xx
{type}	no	返回类型(例如:{Boolean}, {Number}, {String}, {Object}, {String[]})
field	yes	返回id
description	no	参数描述

 例：

"""
@api {get} /user/:id
@apiError UserNotFound The id of the User was not found.
"""

6、@apiErrorExample

接口错误返回示例(格式化输出)

参数列表：

参数	必填	描述
type	no	响应类型
title	no	示例标题
example	yes	示例详情(兼容多行)

 

例:

"""
@api {get} /user/:id
@apiErrorExample {json} Error-Response:
     HTTP/1.1 404 Not Found
    {
       "error": "UserNotFound"
     }
"""

7、@apiExample

接口方式请求示例

参数列表：

参数	必填	描述
type	no	请求内容格式
title	yes	示例标题
example	yes	示例详情(兼容多行)

8、@apiGroup

定义接口所属的接口组，虽然接口定义里不需要这个参数，但是您应该在每个接口注释里都添加这个参数，因为导出的接口文档会以接口组的形式导航展示。

参数列表：

参数	必填	描述
type	no	请求内容格式

例：

"""
@api {get} /user/:id
@apiGroup User
"""

 9、@apiHeader

描述接口请求头部需要的参数(功能类似@apiParam)

参数列表：

参数	必填	描述
(group)	no	所有的参数都会以该参数值进行分组(默认Parameter)
{type}	no	返回类型(例如:{Boolean}, {Number}, {String}, {Object}, {String[]})
field	yes	参数名称(定义该头部参数为可选)
[field]	yes	参数名称(定义该头部参数为可选)
=defaultValue	no	参数默认值
description	no	参数描述

例：

"""
@api {get} /user/:id
@apiHeader {String} access-key Users unique access-key.
"""

10、@apiHeaderExample

请求头部参数示例

参数列表：

参数	必填	描述
type	no	请求内容格式
title	no	请求示例标题
example	yes	请求示例详情(兼容多行)

例:

"""
@api {get} /user/:id
@apiHeaderExample {json} Header-Example:
    {
      "Accept-Encoding": "Accept-Encoding: gzip, deflate"
   }
"""

11、@apiIgnore

如果你需要使用该参数，请把它放到注释块的最前面。如果设置了该参数，那么该注释模块将不会被解析(当有些接口还未完成或未投入使用时，可以使用该字段)

参数列表：

参数	必填	描述
hint	no	描接口忽略原因描述

12、@apiName

接口名称，每一个接口注释里都应该添加该字段，在导出的接口文档里会已该字段值作为导航子标题，如果两个接口的@apiVersion和@apiName一样，那么有一个接口的注释将会被覆盖(接口文档里不会展示)

参数列表：

参数	必填	描述
name	yes	接口名称(相同接口版本下所有接口名称应该是唯一的)

 

 

13、@apiParam

接口请求体参数

参数列表:

参数	必填	描述
(group)	no	所有的参数都会以该参数值进行分组(默认Parameter)
{type}	no	返回类型(例如:{Boolean}, {Number}, {String}, {Object}, {String[]})
{type{size}}	no	返回类型,同时定义参数的范围 {string{..5}}意为字符串长度不超过5 {string{2..5}}意为字符串长度介于25之间 `{number{100-999}}`意为数值介于100999之间
{type=allowedValues}	no	参数可选值 {string="small"}意为字符串仅允许值为"small" {string="small","huge"}意为字符串允许值为"small"、"huge" {number=1,2,3,99}意为数值允许值为1、2、3、99 {string {..5}="small","huge"意为字符串最大长度为5并且值允许为:"small"、"huge"
field	yes	参数名称(定义该请求体参数为必填)
[field]	yes	参数名称(定义该请求体参数为可选)
=defaultValue	no	参数默认值
description	no	参数描述

14、@apiParamExample

请求体参数示例

参数列表:

参数	必填	描述
type	no	请求内容格式
title	no	请求示例标题
example	yes	请求示例详情(兼容多行)

例：

"""
@api {get} /user/:id
@apiParamExample {json} Request-Example:
     {
       "id": 4711
     }
"""

15、@apiPermission

允许访问该接口的角色名称

参数列表:

参数	必填	描述
name	yes	允许访问的角色名称(唯一)

例：

"""
@api {get} /user/:id
@apiPermission admin
"""

16、@apiPrivate

定义私有接口，对于定义为私有的接口，可以在生成接口文档的时候，通过在命令行中设置参数 --private false|true来决定导出的文档中是否包含私有接口

17、@apiSampleRequest

设置了该参数后，导出的html接口文档中会包含模拟接口请求的form表单；如果在配置文件apidoc.json中设置了参数sampleUrl,那么导出的文档中每一个接口都会包含模拟接口请求的form表单，如果既设置了sampleUrl参数，同时也不希望当前这个接口不包含模拟接口请求的form表单，可以使用@apiSampleRequest off来关闭。

参数列表:

参数	必填	描述
url	yes	模拟接口请求的url @apiSampleRequest http://www.example.com意为覆盖apidoc.json中的sampleUrl参数 @apiSampleRequest off意为关闭接口测试功能

18、 @apiSuccess

@apiSuccess [(group)] [{type}] field [description]

接口成功返回参数
参数列表:

参数	必填	描述
(group)	no	所有的参数都会以该参数值进行分组,默认值:Success 200
{type}	no	返回类型(例如:{Boolean}, {Number}, {String}, {Object}, {String[]})
field	yes	返回值(返回成功码)
=defaultValue	no	参数默认值
description	no	参数描述

例:

"""
@api {get} /user/:id
@apiSuccess {String} firstname Firstname of the User.
@apiSuccess {String} lastname  Lastname of the User.
"""

包含(group):

"""
@api {get} /user/:id
@apiSuccess (200) {String} firstname Firstname of the User.
@apiSuccess (200) {String} lastname  Lastname of the User.
"""

返回参数中有对象:

"""
@api {get} /user/:id
@apiSuccess {Boolean} active        Specify if the account is active.
@apiSuccess {Object}  profile       User profile information.
@apiSuccess {Number}  profile.age   Users age.
@apiSuccess {String}  profile.image Avatar-Image.

"""

返回参数中有数组：

"""
@api {get} /users
@apiSuccess {Object[]} profiles       List of user profiles.
@apiSuccess {Number}   profiles.age   Users age.
@apiSuccess {String}   profiles.image Avatar-Image.
"""

19、 @apiSuccessExample

@apiSuccessExample [{type}] [title]
                   example

返回成功示例
参数列表:

参数	必填	描述
type	no	返回内容格式
title	no	返回示例标题
example	yes	返回示例详情(兼容多行)

例：

"""
@api {get} /user/:id
@apiSuccessExample {json} Success-Response:
     HTTP/1.1 200 OK
     {
       "firstname": "John",
       "lastname": "Doe"
     }
"""

20、@apiUse

@apiUse name

引入注释模块,就是前面提到的@apiDefine定义的注释块，如果当前模块定义了@apiVersion,那么版本相同或版本最近的注释模块会被引入
参数列表:

参数	必填	描述
name	yes	引入注释模块的名称

例:

"""
@apiDefine MySuccess
@apiSuccess {string} firstname The users firstname.
@apiSuccess {number} age The users age.
"""

"""
@api {get} /user/:id
@apiUse MySuccess
"""

21、 @apiVersion

@apiVersion version

定义接口/注释模块版本
参数列表:

参数	必填	描述
version	yes	版本号(支持APR版本规则:major.minor.patch)

例:

"""
 @api {get} /user/:id
 @apiVersion 1.6.2
"""

 

原文参考: [apidoc官方文档(翻译)](https://www.jianshu.com/p/9353d5cc1ef8)

原文参考: [apidoc官方文档](http://apidocjs.com/#param-api-define)