apidoc_apidoc 模板 - CSDN
精华内容
参与话题
  • apiDoc自动化文档同步工具

    千人学习 2018-10-22 21:38:05
    学习该课程,可以通过简单的配置,一个命令就能自动生成接口文档,直接使用浏览器可以查看,实时更新。方便前后端开发人员查看,生成的接口文档简单明了,抛弃传统的手工编写文档,而且适合大部分主流语言java、...
  • apidoc实例

    2019-09-04 11:53:07
    /** * @apiDefine MyError * @apiError {String} msg 失败描述 * @apiError {String} code 失败标识,值为0 * @apiError {Integer} data 失败返回数据,可能为空 * @apiErrorExample {json} Error-Response:...
        /**
         * @apiDefine MyError
         * @apiError {String} msg 失败描述
         * @apiError {String} code 失败标识,值为0
         * @apiError {Integer} data 失败返回数据,可能为空
         * @apiErrorExample {json} Error-Response:
         *     HTTP/1.1 404 Not Found
         *     {
         *      "code":0,
         *      "msg":"获取失败",
         *      "time":"1564261895",
         *      "data":null
         *     }
         */
    
    
        /**
         * @api {post} /api/store/getStoreDesc 获取店铺具体信息
         * @apiDescription 根据店铺id或商户手机号获取店铺具体信息
         * @apiVersion 1.0.1
         * @apiName getStoreUserDesc
         * @apiGroup STOREUSER
         *
         *
         * @apiParam {Integer} id 用户id (和手机号二选一)
         * @apiParam {String} mobile 手机号(和用户id二选一)
         *
         *
         * @apiSuccess {String} msg 成功描述
         * @apiSuccess {String} code 成功标识,值为1
         * @apiSuccess {Array} data 成功返回数据
         *
         *
         * @apiSampleRequest /api/store/getStoreDesc
         *
         * @apiSuccessExample Success-Response:
         *     HTTP/1.1 200 OK
         *     {
         *     "code":1,
         *     "msg":"获取成功",
         *     "time":"1564262836",
         *     "data":[
         *          {
         *              "id":1,
         *              "store_name":"小店",//商家名称
         *              "business_license":"/uploads/20190728/099618409d8beebc597619a5ffffb154.jpg",//营业执照
         *              "status":1,//1=正常 2 = 审核中 3 = 拒绝 4 = 禁用
         *              "ctime":1564243971,
         *              "utime":1564243977,
         *          },
         *      ]
         *     }
         * @apiUse MyError
         * @Author: Areom <476423049@qq.com>
         */
        public function getStoreDesc()
        {
             //逻辑。。。。
        }

     效果如下:

     

     

     

    展开全文
  • apiDoc使用指南

    2020-09-17 15:11:33
    apiDoc使用指南: 安装: 1: 需要先安装node.js(安装node.js请浏览相关博客) 2: node.js安装完成后使用命令: npm install apidoc -g 配置: 在你的项目根路径下新建apidoc.json文件,该文件描述了项目对外提供接口的...

    apiDoc使用指南:

    安装:
    1: 需要先安装node.js(安装node.js请浏览相关博客)
    2: node.js安装完成后使用命令:
    npm install apidoc -g


    配置:

    在你的项目根路径下新建apidoc.json文件,该文件描述了项目对外提供接口的概要信息如名称,版本,描述文档打开时浏览器显示标题和接口缺省访问地址.


    使用样例:

    /**
     *
     * @apiDefine RkNotFoundException
     *
     * @apiError RkNotFoundException 找不到相关数据
     *
     * @apiErrorExample Error-Response:
     *     HTTP/1.1 404 Not Found
     *     {
     *       "error": {
     *           "code": 404,
     *           "msg": "",
     *           "path" ""
     *       }
     *     }
     *
     */
    
    /**
     *
     * @api {get} /v3.1/ues/:sn/rt-info 获取设备上报实时信息
     * @apiVersion 3.1.0
     * @apiName GetUeRealTimeInfo
     * @apiGroup UE
     *
     * @apiHeader {String} Authorization 用户授权token
     * @apiHeader {String} firm 厂商编码
     * @apiHeaderExample {json} Header-Example:
     *     {
     *       "Authorization": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOjM2NzgsImF1ZGllbmNlIjoid2ViIiwib3BlbkFJZCI6MTM2NywiY3JlYXRlZCI6MTUzMzg3OTM2ODA0Nywicm9sZXMiOiJVU0VSIiwiZXhwIjoxNTM0NDg0MTY4fQ.Gl5L-NpuwhjuPXFuhPax8ak5c64skjDTCBC64N_QdKQ2VT-zZeceuzXB9TqaYJuhkwNYEhrV3pUx1zhMWG7Org",
     *       "firm": "cnE="
     *     }
     *
     * @apiParam {String} sn 设备序列号
     *
     * @apiSuccess {String} sn 设备序列号
     * @apiSuccess {Number} status 设备状态
     * @apiSuccess {Number} soc 电池电量百分比
     * @apiSuccess {Number} voltage 电池电压
     * @apiSuccess {Number} current 电池电流
     * @apiSuccess {Number} temperature 电池温度
     * @apiSuccess {String} reportTime 上报时间(yyyy-MM-dd HH:mm:ss)
     *
     * @apiSuccessExample Success-Response:
     *     HTTP/1.1 200 OK
     *     {
     *       "sn": "P000000000",
     *       "status": 0,
     *       "soc": 80,
     *       "voltage": 60.0,
     *       "current": 10.0,
     *       "temperature": null,
     *       "reportTime": "2018-08-13 18:11:00"
     *     }
     *
     * @apiUse RkNotFoundException
     *
     */
    @RequestMapping(value = "/{sn}/rt-info", method = RequestMethod.GET)
    public UeRealTimeInfo getUeRealTimeInfo(@RequestHeader(Constants.HEADER_LOGIN_USER_KEY) long userId, @PathVariable("sn") String sn) {
    
        return ueService.getRealTimeInfo(sn);
    }
    

    样式解读:

    @api ( @api {method} path [title] ) HTTP接口调用方法,路径及名称

    @apiVersion ( @apiVersion version ) api版本号

    @apiName (@apiName name) api名称

    @apiGroup (@apiGroup name) api分组

    @apiHeader (@apiHeader [(group)] [{type}] [field=defaultValue] [description]) 请求头参数

    @apiParam (@apiParam [(group)] [{type}] [field=defaultValue] [description]) 请求参数

    @apiSuccess (@apiSuccess [(group)] [{type}] field [description]) 返回数据描述

    @apiSuccessExample( @apiSuccessExample [{type}] [title] example ) 接口成功返回样例

    @apiError @apiError [(group)] [{type}] field [description] 接口失败描述

    @apiErrorExample (@apiErrorExample [{type}] [title] example ) 接口失败返回样例

    @apiDefine (@apiDefine name [title] [description] ) 类似于宏定义,可以被引用

    @apiUse ( @apiUse name ) 使用@apiDefine定义的描述

    生成文档:

    cd到apidoc.json所在路径(即项目根目录)执行命令:
    apidoc -i src/ -o apidoc/

    展开全文
  • apiDoc 详解 api接口文档生成

    万次阅读 2019-02-20 14:35:45
    PHP使用apiDoc api接口文档安装apidocapidoc 命令参数列表配置(apidoc.json)apidoc.json配置项apidoc注释参数@api@apiErrorExample@apiDefine@apiDeprecated@apiDescription@apiError@apiExample@apiGroup@apiParam@...

    安装apidoc

    官网

    通过npm安装,请提前安装好npm

    可以通过以下命令安装apidoc:

    npm install apidoc -g
    

    配置(apidoc.json)

    每次导出接口文档都必须要让apidoc读取到apidoc.json文件(如果未添加配置文件,导出报错),你可以在你项目的根目录下添加apidoc.json文件,这个文件主要包含一些项目的描述信息,比如标题、简短的描述、版本等,你也可以加入一些可选的配置项,比如页眉、页脚、模板等。
    apidoc.json

    {
      "name": "系统接口文档",
      "version": "0.0.1",
      "description": "文档总描述",
      "title": "apidoc浏览器自定义标题",
      "url" : "文档url地址"
    }
    

    如果你的项目中使用了package.json文件(例如:node.js工程),那么你可以将apidoc.json文件中的所有配置信息放到package.json文件中的apidoc参数中:
    package.json

    {
     "name": "系统接口文档",
      "version": "0.0.1",
      "description": "文档总描述",
      "apidoc": {
        "title": "apidoc浏览器自定义标题",
     	 "url" : "文档url地址"
      }
    }
    

    apidoc.json配置项

    参数 描述
    name 工程名称如果apidoc.json文件中没有配置该参数,apidoc会尝试从pakcage.json文件中读取
    version 版本如果apidoc.json文件中没有配置该参数,apidoc会尝试从pakcage.json文件中读取
    description 工程描述如果apidoc.json文件中没有配置该参数,apidoc会尝试从pakcage.json文件中读取
    title 浏览器标题
    url api路径前缀例如:https://api.github.com/v1
    sampleUrl 如果设置了该参数,那么在文档中便可以看到用于测试接口的一个表单(详情可以查看参数@apiSampleReques)
    header.title 页眉导航标题
    header.filename 页眉文件名(markdown)
    footer.title 页脚导航标题
    footer.filename 页脚文件名(markdown)
    order 接口名称或接口组名称的排序列表如果未定义,那么所有名称会自动排序"order": [ "Error", "Define", "PostTitleAndError", PostError"]

    更多详情

    apidoc注释参数

    @api

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

    @api {method} path [title]
    

    参数列表:

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

    例:

    /**
    * @api {get} /user/getUserById/:id 获取用户数据 - 根据id
    */
    

    @apiErrorExample

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

    @apiErrorExample [{type}] [title]
                     example
    

    参数列表:

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

    例:

    /**
     *@api {get} /user/getUserById/:id 获取用户数据 - 根据id
     * @apiErrorExample {json} Error-Response:
     *     HTTP/1.1 404 Not Found
     *     {
     *       "error": "UserNotFound"
     *     }
     */
    

    @apiDefine

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

    @apiDefine name [title] [description]
    

    参数列表:

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

    例:

    /**
     * @apiDefine        FailResponse
     * @apiErrorExample  Response (fail):
     *     {
     *       "code":"error"
     *       "error_message": "错误内容"
     *     }
     */
    
    /**
     * @apiDefine        SuccessResponse
     * @apiSuccessExample  Response (success):
     *     {
     *       "code":"0"
     *       "error_message": ""
     *       "data":"内容"
     *     }
     */
    
    /**
     * @apiUse             SuccessResponse
     *
     * @apiUse             FailResponse
     */
    

    @apiDeprecated

    标注一个接口已经被弃用

    @apiDeprecated [text]
    

    参数列表:

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

    例:

    /**
     * @apiDeprecated use now (#Group:Name).
     *
     * Example: to set a link to the GetDetails method of your group User
     * write (#User:GetDetails)
     */
    

    @apiDescription

    api接口的详细描述

    @apiDescription [text]
    

    参数列表:

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

    例:

    /**
     * @apiDescription This is the Description.
     * It is multiline capable.
     *
     * Last line of Description.
     */
    

    @apiError

    错误返回参数

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

    参数列表:

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

    例:

    /**
     * @api {get} /user/getUserById/:id 获取用户数据 - 根据id
     * @apiError UserNotFound The <code>id</code> of the User was not found.
     */
     
    /**
     * @apiError (错误分组) {Object} xxx xxxxxxxx
     */
    

    @apiExample

    接口方式请求示例

    @apiExample [{type}] title
                example
    

    参数列表:

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

    例:

    /**
     * @api {get} /user/getUserById/:id
     * @apiExample {curl} Example usage:
     *     curl -i http://127.0.0.1/user/getUserById/1
     */
    

    @apiGroup

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

    @apiGroup name
    

    参数列表:

    参数 必填 描述
    name yes 接口组名称(用于导航,不支持中文)

    例:

    /**
     * @apiDefine User 用户信息
     */
    /**
     * @api {get} /user/getUserById/:id
     * @apiGroup User
     */
    

    @apiParam

    接口请求体参数

    @apiParam [(group)] [{type}] [field=defaultValue] [description]
    

    参数列表:

    参数 必填 描述
    (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 参数描述

    例:

    /**
     * @api {get} /user/getUserById/:id
     * @apiParam {Number} id Users unique ID.
     */
    
    /**
     * @api {post} /user/
     * @apiParam {String} [firstname]  Optional Firstname of the User.
     * @apiParam {String} lastname     Mandatory Lastname.
     * @apiParam {String} country="DE" Mandatory with default value "DE".
     * @apiParam {Number} [age=18]     Optional Age with default 18.
     *
     * @apiParam (Login) {String} pass Only logged in users can post this.
     *                                 In generated documentation a separate
     *                                 "Login" Block will be generated.
     */
    

    @apiHeader

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

    @apiHeader [(group)] [{type}] [field=defaultValue] [description]
    

    参数列表:

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

    例:

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

    @apiHeaderExample

    请求头部参数示例

    @apiHeaderExample [{type}] [title]
                       example
    

    参数列表:

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

    例:

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

    @apiIgnore

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

    @apiIgnore [hint]
    

    参数列表:

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

    例:

    /**
     * @apiIgnore Not finished Method
     * @api {get} /user/getUserById/:id
     */
    

    @apiName

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

    @apiName name
    

    参数列表:

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

    例:

    /**
     * @api {get} /user/getUserById/:id
     * @apiName getUserById
     */
    

    @apiParamExample

    请求体参数示例

    @apiParamExample [{type}] [title]
                       example
    

    参数列表:

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

    例:

    /**
     * @api {get} /user/getUserById/:id
     * @apiParamExample {json} Request-Example:
     *     {
     *       "id": 1
     *     }
     */
    

    @apiPermission

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

    @apiPermission name
    

    参数列表:

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

    例:

    /**
     * @api {get} /user/getUserById/:id
     * @apiPermission none
     */
    

    @apiPrivate

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

    @apiPrivate
    

    例:

    /**
     * @api {get} /user/getUserById/:id
     * @apiPrivate
     */
    

    @apiSampleRequest

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

    @apiSampleRequest url
    

    参数列表:

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

    例:
    发送测试请求到:http://api.github.com/user/getUserById/:id

    /**
     * @api {get} /user/getUserById/:id
     */
    

    发送测试请求到:http://test.github.com/some_path/user/getUserById/:id(覆盖apidoc.json中的sampleUrl参数)

    /**
     * @api {get} /user/getUserById/:id
     * @apiSampleRequest http://test.github.com/some_path/
     */
    

    关闭接口测试功能

    /**
     * @api {get} /user/getUserById/:id
     * @apiSampleRequest off
     */
    

    发送测试请求到http://api.github.com/some_path/user/getUserById/:id(由于没有设置apidoc.json中的sampleUrl参数,所以只有当前接口有模拟测试功能)

    /**
     * @api {get} /user/getUserById/:id
     * @apiSampleRequest http://api.github.com/some_path/
     */
    

    @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/getUserById/:id
     * @apiSuccess {String} firstname Firstname of the User.
     * @apiSuccess {String} lastname  Lastname of the User.
     */
    

    包含(group):

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

    返回参数中有对象:

    /**
     * @api {get} /user/getUserById/: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.
     */
    

    @apiSuccessExample

    返回成功示例

    @apiSuccessExample [{type}] [title]
                       example
    

    参数列表:

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

    例:

    /**
     * @api {get} /user/getUserById/:id
     * @apiSuccessExample {json} Success-Response:
     *     HTTP/1.1 200 OK
     *     {
     *       "code":"0"
     *       "message": ""
     *       "data":"加密内容"
     *     }
     */
    

    @apiUse

    引入注释模块,如果当前模块定义了@apiVersion,那么版本相同或版本最近的注释模块会被引入

    @apiUse name
    

    参数列表:

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

    例:

    /**
     * @apiDefine MySuccess
     * @apiSuccess {string} firstname The users firstname.
     * @apiSuccess {number} age The users age.
     */
    
    /**
     * @api {get} /user/getUserById/:id
     * @apiUse MySuccess
     */
    

    @apiVersion

    定义接口/注释模块版本

    @apiVersion version
    

    参数列表:

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

    例:

    /**
     * @api {get} /user/getUserById/:id
     * @apiVersion 1.6.2
     */
    

    小诀窍,笔者把接口中的通用部分利用apiDefine摘出来,放在一个公共文件中,之后可以利用apiUse去调用,或许部分注释参数可以直接使用apiDefine即可调用。

    生成接口文档

    当然你注释参数写好了之后它也不会帮你自动生成,你需要自己运行以下命令:
    例:

    apidoc -f ".*\\.php$"  -i ./application -o ./public/apidoc
    

    参数列表:

    参数 描述
    -h, --help 查看帮助文档
    -f --file-filters 指定读取文件的文件名过滤正则表达式(可指定多个)例如: apidoc -f “.*\.js&quot;f&quot;..ts&quot; -f &quot;.*\\.ts” 意为只读取后缀名为js和ts的文件默认值:.clj .cls .coffee .cpp .cs .dart .erl .exs? .go .groovy .ino? .java .js .jsx .kt .litcoffee lua .p .php? .pl .pm .py .rb .scala .ts .vue
    -e --exclude-filters 指定不读取的文件名过滤正则表达式(可指定多个)例如:apidoc -e “.*\.js$” 意为不读取后缀名为js的文件默认:’’
    -i, --input 指定读取源文件的目录例如:apidoc -i myapp/ 意为读取myapp/目录下面的源文件默认值:./
    -o, --output 指定输出文档的目录例如:apidoc -o doc/ 意为输出文档到doc目录下默认值:./doc/
    -t, --template 指定输出的模板文件例如:apidoc -t mytemplate/默认:path.join(__dirname, ‘…/template/’)(使用默认模板)
    -c, --config 指定包含配置文件(apidoc.json)的目录例如:apidoc -c config/默认:./
    -p, --private 输出的文档中是否包含私有api例如:apidoc -p true 默认:false
    -v, --verbose 是否输出详细的debug信息例如:apidoc -v true默认:false

    之后你就能通过浏览器进行访问了,比如我的是http://localhost/apidoc

    展开全文
  • apidoc的介绍和使用

    千次阅读 2018-02-28 11:33:14
    安装npm install apidoc -g跑apidoc -i myapp/ -o apidoc/ -t mytemplate/创建目录中的所有文件的apiDoc myapp/,使用从目录模板mytemplate/,并把所有输出目录apidoc/。不带任何参数,apiDoc生成全部的文档.cs ....

    安装

    npm install apidoc -g

    apidoc -i myapp/ -o apidoc/ -t mytemplate/

    创建目录中的所有文件的apiDoc myapp/,使用从目录模板mytemplate/,并把所有输出目录apidoc/

    不带任何参数,apiDoc生成全部的文档.cs .dart .erl .go .java .js .php .py .rb .ts文件,在当前目录(包括子目录)和输出写入./doc/

    命令行界面

    显示命令行参数:

    apidoc -h

    重要参数:

    参数描述
    -f,--file过滤器正则表达式过滤来选择应该被解析(多-f可以使用)的文件。默认情况下.cs .dart .erl .go .java .js .php .py .rb .ts

    示例(仅解析和名为.js文件.TS):
    apidoc -f ".*\\.js$" -f ".*\\.ts$"
    -i,--input输入/源目录名。。您的项目文件的位置

    示例:
    apidoc -i myapp/
    -o,--output输出目录名。位置放在哪里来生成文档。

    例如:
    apidoc -o apidoc/
    -t,--template使用模板输出文件。您可以创建和使用自己的模板。

    例如:
    apidoc -t mytemplate/

    配置(apidoc.json)

    可选apidoc.json在项目的根目录包含有关项目如标题,简短描述,版本和类似配置选项通用信息页眉/页脚设置或模板的特定选项。

    apidoc.json

    {
      "name": "example",
      "version": "0.1.0",
      "description": "apiDoc basic example",
      "title": "Custom apiDoc browser title",
      "url" : "https://api.github.com/v1"
    }

    如果您使用package.json(在Node.js的项目如),所有apidoc.json设置都可以在做package.json太多,只是增加他们的下"apidoc": { }参数。

    的package.json

    {
      "name": "example",
      "version": "0.1.0",
      "description": "apiDoc basic example",
      "apidoc": {
        "title": "Custom apiDoc browser title",
        "url" : "https://api.github.com/v1"
      }
    }

    对于apidoc.json设置

    名称描述
    名称项目的名称。
    如果没有apidoc.json与字段存在,则apiDoc尝试,以确定从所述值package.json
    项目的版本。
    如果没有apidoc.json与字段存在,则apiDoc尝试,以确定从所述值package.json
    描述项目简介。
    如果没有apidoc.json与字段存在,则apiDoc尝试,以确定从所述值package.json
    标题浏览器的标题文字。
    网址前缀API路(终点),例如: https://api.github.com/v1
    SAMPLEURL如果设置,窗体来测试API方法(发送请求)将是可见的。见@apiSampleRequest了解更多详情。
        标题导览文本所包含header.md文件。
    (看页眉/页脚
        文件名文件名(降价文件)所包含的header.md文件。
    页脚
        标题导览文本所包含footer.md文件。
        文件名文件名(降价文件)所包含的footer.md文件。
    订购订购输出API-名/组名称的列表。未定义名称会自动显示上次。
    "order": [
      "Error",
      "Define",
      "PostTitleAndError",
      "PostError"
    ]

    模板的具体设置

    以下设置特定于apiDoc的默认模板。

    名称类型描述
    模板
        forceLanguage禁用浏览器语言自动检测并设置特定的语言环境。
    例如:deen
    查看可用区域设置在这里
        withCompare布尔启用与旧的API版本比较。默认:true
        withGenerator布尔在输出页脚中产生的信息。默认:true
        jQueryAjaxSetup目的设为默认值的Ajax请求。

    页眉页脚

    在你的项目apidoc.json,你可以添加页眉和页脚。

    标题将在导航中可见。文件名应该是一个文本文件降价。

    apidoc.json

    {
      "header": {
        "title": "My own header title",
        "filename": "header.md"
      },
      "footer": {
        "title": "My own footer title",
        "filename": "footer.md"
      }
    }

    例子

    介绍演示用一个小例子可以发现speakerdeck.com

    基本

    在这个基本的例子,我们有一个小项目文件和apidoc.json。

    查看示例输出


    apidoc.json

    {
      "name": "example",
      "version": "0.1.0",
      "description": "A basic apiDoc example"
    }

    apidoc.jsonapiDoc获得项目的名称,版本和说明。
    该文件optional(这取决于你的模板,如果需要对数据)。


    example.js

    /**
     * @api {get} /user/:id Request User information
     * @apiName GetUser
     * @apiGroup User
     *
     * @apiParam {Number} id Users unique ID.
     *
     * @apiSuccess {String} firstname Firstname of the User.
     * @apiSuccess {String} lastname  Lastname of the User.
     *
     * @apiSuccessExample Success-Response:
     *     HTTP/1.1 200 OK
     *     {
     *       "firstname": "John",
     *       "lastname": "Doe"
     *     }
     *
     * @apiError UserNotFound The id of the User was not found.
     *
     * @apiErrorExample Error-Response:
     *     HTTP/1.1 404 Not Found
     *     {
     *       "error": "UserNotFound"
     *     }
     */

    一个文档块开头/**和结尾*/

    本例介绍一个GET方法来请求用户的用户信息id

    @api {get} /user/:id Request User information是必需的,没有@apiapiDoc忽略一个文档块。

    @apiName是一个unique名称,应始终使用。
    格式: + 路径(如获取+用户)

    @apiGroup 应始终使用,根据该名称将这个方法进行分组。

    所有其他字段都是可选的,看看在他们的描述apiDoc-PARAMS

    继承

    继承的意思是,你可以定义你的文档,应多次使用的部分。

    查看示例输出


    apidoc.json

    {
      "name": "example-inherit",
      "version": "0.1.0",
      "description": "apiDoc inherit example"
    }


    example.js

    /**
     * @apiDefine UserNotFoundError
     *
     * @apiError UserNotFound The id of the User was not found.
     *
     * @apiErrorExample Error-Response:
     *     HTTP/1.1 404 Not Found
     *     {
     *       "error": "UserNotFound"
     *     }
     */
    
    /**
     * @api {get} /user/:id Request User information
     * @apiName GetUser
     * @apiGroup User
     *
     * @apiParam {Number} id Users unique ID.
     *
     * @apiSuccess {String} firstname Firstname of the User.
     * @apiSuccess {String} lastname  Lastname of the User.
     *
     * @apiSuccessExample Success-Response:
     *     HTTP/1.1 200 OK
     *     {
     *       "firstname": "John",
     *       "lastname": "Doe"
     *     }
     *
     * @apiUse UserNotFoundError
     */
    
    /**
     * @api {put} /user/ Modify User information
     * @apiName PutUser
     * @apiGroup User
     *
     * @apiParam {Number} id          Users unique ID.
     * @apiParam {String} [firstname] Firstname of the User.
     * @apiParam {String} [lastname]  Lastname of the User.
     *
     * @apiSuccessExample Success-Response:
     *     HTTP/1.1 200 OK
     *
     * @apiUse UserNotFoundError
     */

    在这种情况下,一个命名块UserNotFoundError与定义@apiDefine
    也就是说块可以与使用多次@apiUse UserNotFoundError

    在所产生的输出,这两种方法GET and PUT将具有完整UserNotFoundError文档。


    继承定义的命令是apiDefine
    使用的名字是apiUse, apiGroup并且apiPermission是使用命令,但在他们的背景下,不能继承参数,只有标题和描述(结合apiVersion)。

    Inheritation只适用于1父,多层次将使内嵌代码不可读和变化非常复杂。

    版本

    不错的功能是以前定义的文件块的保持。这使得它能够比较一个方法的版本与它的前身。前端开发者可以简单地这样看什么已经改变和修改他们的代码。

    查看示例输出

    在这个例子中,单击选择框(主版),并选择右上角Compare all with predecessor

    • 主要的航标一切都改变了方法,用绿色吧。
    • 每种方法示区别,它的前身。
    • 添加的绿色标志的内容(在这种情况下,标题的文本改变和字段registered中加入)。
    • 被删除的红色标记的内容。

    您可以更改主版(右上)到以前的版本,并同他们的前任老方法。


    apidoc.json

    {
      "name": "example-versioning",
      "version": "0.2.0",
      "description": "apiDoc versioning example"
    }


    使你的代码与文档块吹出来的,我更喜欢使用一个单独的名为历史文件_apidoc.js。在您更改文档块,旧块复制到这个文件,仅此而已。

    _apidoc.js

    /**
     * @api {get} /user/:id Get User information
     * @apiVersion 0.1.0
     * @apiName GetUser
     * @apiGroup User
     *
     * @apiParam {Number} id Users unique ID.
     *
     * @apiSuccess {String} firstname Firstname of the User.
     * @apiSuccess {String} lastname  Lastname of the User.
     *
     * @apiSuccessExample Success-Response:
     *     HTTP/1.1 200 OK
     *     {
     *       "firstname": "John",
     *       "lastname": "Doe"
     *     }
     *
     * @apiError UserNotFound The id of the User was not found.
     *
     * @apiErrorExample Error-Response:
     *     HTTP/1.1 404 Not Found
     *     {
     *       "error": "UserNotFound"
     *     }
     */

    example.js(当前项目文件)

    /**
     * @api {get} /user/:id Get User information and Date of Registration.
     * @apiVersion 0.2.0
     * @apiName GetUser
     * @apiGroup User
     *
     * @apiParam {Number} id Users unique ID.
     *
     * @apiSuccess {String} firstname  Firstname of the User.
     * @apiSuccess {String} lastname   Lastname of the User.
     * @apiSuccess {Date}   registered Date of Registration.
     *
     * @apiSuccessExample Success-Response:
     *     HTTP/1.1 200 OK
     *     {
     *       "firstname": "John",
     *       "lastname": "Doe"
     *     }
     *
     * @apiError UserNotFound The id of the User was not found.
     *
     * @apiErrorExample Error-Response:
     *     HTTP/1.1 404 Not Found
     *     {
     *       "error": "UserNotFound"
     *     }
     */

    重要的是要与设置版本@apiVersion每一个文档块上。


    版本可以每块上使用,也继承块。你不必自动改变一个继承块上的版本,解析器检查为最近的前身。

    完整的示例(一起)

    这是一个复杂的例子inheritversioning文件,历史文件_apidoc.js,解释是在代码和生成的文档。

    查看示例输出


    文件:

    apiDoc-PARAMS

    结构参数,如:

    • @apiDefine

    用于定义一个文档块为草稿。该草案可以包含在正常的API文档块。有了草稿可以单独复杂的或复发的块。

    已定义的块可以拥有所有PARAMS(像@apiParam),除其他定义的块

    @api

    @api {method} path [title]

    需要!

    如果没有这个指标,apiDoc解析器忽略文档块。

    除了定义块一样@apiDefine,它们并不需要@api

    用法: @api {get} /user/:id Users unique ID.

    名称描述
    方法申请方法名称:DELETEGETPOSTPUT,... 
    更多信息维基百科的HTTP Request_methods
    路径请求路径。
    标题可选一个简短的标题。(用于导航和文章标题)

    例:

    /**
     * @api {get} /user/:id
     */

    @apiDefine

    @apiDefine name [title]
                         [description]

    定义为在使用的草案的允许@api块或类似的API函数@apiPermission

    @apiDefine 只能每块使用一次

    有了@apiUse一个定义的块将被导入,或名称的标题和描述将被使用。

    用法: @apiDefine MyError

    名称描述
    名称为块/值唯一的名字。
    用不同的名字相同@apiVersion可以被定义。
    标题可选一个简短的标题。仅用于像命名函数@apiPermission@apiParam (name)
    说明可选在下一行详细说明的开始,可以使用多行。仅用于像命名函数@apiPermission

    例:

    /**
     * @apiDefine MyError
     * @apiError UserNotFound The <code>id</code> of the User was not found.
     */
    
    /**
     * @api {get} /user/:id
     * @apiUse MyError
     */
    /**
     * @apiDefine admin User access only
     * This optional description belong to to the group admin.
     */
    
    /**
     * @api {get} /user/:id
     * @apiPermission admin
     */

    欲了解更多的手表继承的例子

    @apiDescription

    @apiDescription text

    的API方法的详细描述。

    用法: @apiDescription This is the Description.

    名称描述
    文本多行说明文字。

    例:

    /**
     * @apiDescription This is the Description.
     * It is multiline capable.
     *
     * Last line of Description.
     */
    

    @apiError

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

    错误返回参数。

    用法: @apiError UserNotFound

    名称描述
    (集团)可选所有参数将被这个名字进行分类。
    如果没有一个组,默认的Error 4xx设置,
    可以设置标题和描述与@apiDefine
    {}型可选返回类型,例如{Boolean}, {Number}, {String}{Object}{String[]}(字符串数组),...
    领域返回标识符(返回错误代码)。
    说明可选字段的描述。

    例:

    /**
     * @api {get} /user/:id
     * @apiError UserNotFound The <code>id</code> of the User was not found.
     */

    @apiErrorExample

    @apiErrorExample [{type}] [title]
                     example

    返回错误消息,输出作为预格式化代码的例子。

    用法: @apiErrorExample {json} Error-Response:
    This is an example.

    名称描述
    类型可选响应格式。
    标题可选简短标题的例子。
    详细的例子,多线能力。

    例:

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

    @apiExample

    @apiExample [{type}] title
                example

    例如,对于一个API方法的使用。输出作为预格式化的代码。

    在端点的描述的开始使用它的一个完整的例子。

    用法: @apiExample {js} Example usage:
    This is an example.

    名称描述
    类型可选代码语言。
    标题简短标题的例子。
    详细的例子,多线能力。

    例:

    /**
     * @api {get} /user/:id
     * @apiExample {curl} Example usage:
     *     curl -i http://localhost/user/4711
     */

    @apiGroup

    @apiGroup name

    应始终使用。

    定义的方法的文档块属于哪个组。组将被用于在生成的输出的主导航。结构定义并不需要@apiGroup

    用法: @apiGroup User

    名称描述
    名称该组的名称。也用作导航称号。

    例:

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

    @apiHeader

    @apiHeader [(group)] [{type}] [field=defaultValue] [description]

    描述传递给你的API标头如为授权的参数。

    类似的操作,@apiParam,只输出上述参数。

    用法: @apiHeader (MyHeaderGroup) {String} authorization Authorization value.

    名称描述
    (集团)可选所有参数将被这个名字进行分类。
    如果没有一个组,默认的Parameter设置,
    可以设置标题和描述与@apiDefine
    {}型可选参数类型,例如{Boolean}, {Number}, {String}{Object}{String[]}(字符串数组),...
    领域变量名。
    [领域]字段名用方括号将变量定义为可选的。
    =设置defaultValue可选该参数的默认值。
    说明可选字段的描述。

    例子:

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

    @apiHeaderExample

    @apiHeaderExample [{type}] [title]
                       example

    参数请求示例。

    用法: @apiHeaderExample {json} Request-Example:
    { "content": "This is an example content" }

    名称描述
    类型可选请求格式。
    标题可选简短标题的例子。
    详细的例子,多线能力。

    例:

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

    @apiIgnore

    @apiIgnore [hint]

    将其放置在一个块的顶部。

    带座@apiIgnore不会被解析。它是有用的,如果你留在你的源代码已经过时或没有完成的方法和你不希望将其发布到文档。

    用法: @apiIgnore Not finished Method

    名称描述
    提示可选短信息为什么这个块应该被忽略。

    例:

    /**
     * @apiIgnore Not finished Method
     * @api {get} /user/:id
     */

    @apiName

    @apiName name

    应始终使用。

    定义方法的文档块的名称。名称将被用于在生成的输出小组导航。结构定义并不需要@apiName

    用法: @apiName GetUser

    名称描述
    名称该方法的唯一名称。用不同的名称相同@apiVersion,可以定义
    格式: + 路径(如获取+用户),只有一个建议,只要你想,你可以命名。
    也用作导航称号。

    例:

    /**
     * @api {get} /user/:id
     * @apiName GetUser
     */

    @apiParam

    @apiParam [(group)] [{type}] [field=defaultValue] [description]

    描述传递给您的API-方法的参数。

    用法: @apiParam (MyGroup) {Number} id Users unique ID.

    名称描述
    (集团)可选所有参数将被这个名字进行分类。
    如果没有一个组,默认的Parameter设置,
    可以设置标题和描述与@apiDefine
    {}型可选参数类型,例如{Boolean}{Number}{String}{Object}{String[]}(字符串数组),...
    {{型大小}}可选关于变量的大小的信息。
    {string{..5}}具有最多5个字符的字符串。
    {string{2..5}}具有最小字符串。2个字符和最大字符5,
    {number{100-999}}在100和999之间的数字。
    {类型= ALLOWEDVALUES}可选关于变量的允许值的信息。
    {string="small"}只能包含单词“小”(一个常数)。一个字符串
    {string="small","huge"},它可以包含词语“小”或“大”。字符串
    {number=1,2,3,99}一批具有的1允许值,2,3 99 

    :可与大小组合
    {string {..5}="small","huge"}有最多5个字符,只包含单词串“小”或“庞大”。
    领域变量名。
    [领域]字段名用方括号将变量定义为可选的。
    =设置defaultValue可选该参数的默认值。
    说明可选字段的描述。

    例子:

    /**
     * @api {get} /user/:id
     * @apiParam {Number} id Users unique ID.
     */
    
    /**
     * @api {post} /user/
     * @apiParam {String} [firstname]  Optional Firstname of the User.
     * @apiParam {String} lastname     Mandatory Lastname.
     * @apiParam {String} country="DE" Mandatory with default value "DE".
     * @apiParam {Number} [age=18]     Optional Age with default 18.
     *
     * @apiParam (Login) {String} pass Only logged in users can post this.
     *                                 In generated documentation a separate
     *                                 "Login" Block will be generated.
     */

    @apiParamExample

    @apiParamExample [{type}] [title]
                       example

    参数请求示例。

    用法: @apiParamExample {json} Request-Example:
    { "content": "This is an example content" }

    名称描述
    类型可选请求格式。
    标题可选简短标题的例子。
    详细的例子,多线能力。

    例:

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

    @apiPermission

    @apiPermission name

    输出权限名称。如果该名称与定义@apiDefine生成的文档包括附加的标题和描述。

    用法: @apiPermission admin

    名称描述
    名称许可的唯一名称。

    例:

    /**
     * @api {get} /user/:id
     * @apiPermission none
     */

    @apiSampleRequest

    @apiSampleRequest url

    与apidoc.json配置参数一起使用此参数SAMPLEURL

    如果sampleUrl被设置,所有的方法将有API测试形式(从端点@api将被追加)。
    如果没有SAMPLEURL只与方法@apiSampleRequest将有一个表格。

    如果@apiSampleRequest url在方法块设置,这个网址将被用于请求(它将覆盖SAMPLEURL当它以http开头)。

    如果sampleUrl已设置,你不想与测试形式的方法,然后添加@apiSampleRequest off到文档块。

    用法: @apiSampleRequest http://test.github.com

    名称描述
    网址URL到您的测试API服务器。

    覆盖的配置参数SAMPLEURL并追加@api网址:
    @apiSampleRequest http://www.example.com

    前缀的@api:URL 
    @apiSampleRequest /my_test_path

    ,如果配置参数SAMPLEURL设置禁用API的测试:
    @apiSampleRequest off

    例子:

    这将API请求发送到http://api.github.com/user/:id

    Configuration parameter sampleUrl: "http://api.github.com"
    /**
     * @api {get} /user/:id
     */

    这将发送API请求http://test.github.com/some_path/user/:id~~V
    它覆盖SAMPLEURL。

    Configuration parameter sampleUrl: "http://api.github.com"
    /**
     * @api {get} /user/:id
     * @apiSampleRequest http://test.github.com/some_path/
     */

    这将发送API请求http://api.github.com/test/user/:id~~V
    它扩展SAMPLEURL。

    Configuration parameter sampleUrl: "http://api.github.com"
    /**
     * @api {get} /user/:id
     * @apiSampleRequest /test
     */

    这将禁用此API的方法API请求。

    Configuration parameter sampleUrl: "http://api.github.com"
    /**
     * @api {get} /user/:id
     * @apiSampleRequest off
     */

    这将发送API请求http://api.github.com/some_path/user/:id~~V
    它激活仅此法的要求,因为SAMPLEURL未设置。

    Configuration parameter sampleUrl is not set
    /**
     * @api {get} /user/:id
     * @apiSampleRequest http://api.github.com/some_path/
     */

    @apiSuccess

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

    成功返回参数。

    用法: @apiSuccess {String} firstname Firstname of the User.

    名称描述
    (集团)可选所有参数将被这个名字进行分类。
    如果没有一个组,默认的Success 200设置,
    可以设置标题和描述与@apiDefine
    {}型可选返回类型,例如{Boolean}, {Number}, {String}{Object}{String[]}(字符串数组),...
    领域返回标识符(返回成功代码)。
    说明可选字段的描述。

    例:

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

    例如用(group)在更多组的例子@apiSuccessTitle

    /**
     * @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.
     */

    示例使用Array:

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

    @apiSuccessExample

    @apiSuccessExample [{type}] [title]
                       example

    一个成功返回消息,输出作为预格式化代码的例子。

    用法: @apiSuccessExample {json} Success-Response:
    { "content": "This is an example content" }

    名称描述
    类型可选响应格式。
    标题可选简短标题的例子。
    详细的例子,多线能力。

    例:

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

    @apiUse

    @apiUse name

    包括与@apiDefine定义的块。如果与使用@apiVersion相同的或最近的前身将包括在内。

    用法: @apiUse MySuccess

    名称描述
    名称定义的块的名称。

    例:

    /**
     * @apiDefine MySuccess
     * @apiSuccess {string} firstname The users firstname.
     * @apiSuccess {number} age The users age.
     */
    
    /**
     * @api {get} /user/:id
     * @apiUse MySuccess
     */

    @apiVersion

    @apiVersion version

    设置文档块的版本。版本也可使用@apiDefine

    与同组和名称,但不同版本的块可以在生成的输出进行比较,所以你还是一个前端开发人员可以追溯的API中从上一版本有什么变化。

    用法: @apiVersion 1.6.2

    名称描述
    支持简单的版本(major.minor.patch)。有关更多信息语义版本规格(SemVer) 

    例:

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

    欲了解更多的手表版本的例子


    展开全文
  • 使用apidoc 生成Restful web Api文档

    万次阅读 热门讨论 2020-01-16 10:04:10
    在项目开发过程中,总会牵扯到接口文档的设计与编写,之前使用的都是office工具,写一个文档,总也是不够漂亮和直观。...工具名称:apiDoc Git地址:https://github.com/apidoc/apidoc 项目地址:http://apidocjs
  • Spring项目集成apidoc生成api接口文档

    万次阅读 2018-01-29 14:38:41
    一、背景需求 ...在之后的项目都有一一尝试,最终还是觉得apidoc的方式比较合适,虽然有一些问题(针对在线测试方面),但可以进行定制修复并解决。 二、方案对比 1.现在大家普遍使用的是swagger结合springmv
  • Apidoc使用说明

    千次阅读 2019-02-11 17:36:30
    Apidoc 使用说明 使用apidocJs快速生成在线文档 apidoc是一个轻量级的在线REST接口文档生成系统,支持多种主流语言,包括Java、C、C#、PHP和JavaScript等。使用者仅需要按照要求书写相关注释,就可以生成可读性好、...
  • ApiDoc 一键生成注释

    千次阅读 2018-09-19 10:55:22
    我们日常在使用ApiDoc维护管理api文档,提高了api文档的整体维护性。但在老旧接口中,补充接口注解无疑是一次繁重的体力劳动。仔细查看,大多数接口的格式 其实是相似的,那么,是否可以将体力活做的技术一些? 答案...
  • 首先声明下,apidoc是基于注释来生成文档的,它不基于任何框架,而且支持大多数编程语言,为了springboot系列的完整性,所以标了个题。一、apidoc简介apidoc通过在你代码的注释来生成api文档的。它对代码没有侵入性...
  • Apidoc的安装和使用简介 1、apidoc是什么? apidoc是一个可以将源代码中的注释直接生成api接口文档的工具,它支持各种不同的注释风格,可以在各种语言中使用。 具体见官网介绍:apidoc官网 2、apidoc的安装 第一步...
  • 使用apidoc自动生成接口文档

    千次阅读 2018-04-09 11:35:53
    1.apidoc的使用需借助npm,即你首先需要安装node js2.然后开始-&gt;运行-&gt;cmd-&gt;npm install apidoc -g 进行全局安装apidoc可通过apidoc -v 命令查看是否安装成功3.通过apidoc -f ".*\.java$&...
  • ApiDoc json格式提交参数

    千次阅读 2019-03-10 10:36:11
    我们默认安装的apidoc,提供了在线测试接口的功能,但是默认的参数提交是form表单提交,而我们编写的接口通常是restful的接口,一般都是采用json格式的数据提交,那我们怎么把默认的参数格式修改为我们想要的json...
  • 使用apidoc生成api文档

    千次阅读 2019-03-19 16:01:53
    为什么要用apidoc apidoc根据其自定义注释语法自动生成api文档,我们只需要把代码中的注释按照其语法来写就能生成需要的文档,不需要手动写markdown。 apidoc生成的文档相比markdown,漂亮直观又实用。 如果API需要...
  • 使用apidoc 生成Api接口文档

    千次阅读 2018-06-19 13:21:35
    前言: ...apidoc是一个轻量级的在线接口文档生成系统,仅需要按照要求书写相关注释,就可以生成可读性好、界面美观的在线接口文档 一、apidoc的基本概念 apoDoc是从源码的注释中生成RestFul...
  • 自动生成API文档-apidoc

    千次阅读 2018-08-20 18:51:43
    对于一个后台开发者编写接口文档是必不可少的一件事,但是手动编写又很麻烦,网上出现了很多自动化生成的API文档框架,本篇文章就来介绍一下apidoc的在node开发过程中的基本使用。 用法 npm安装 对于我们在...
  • apiDoc是我们在日常开发中经常会使用到的一款开源的api文档解析框架,使用apiDoc可以轻松的将我们代码中的api解析成为可以方便阅读的api文档,只需轻松的按照格式进行编辑即可,使用起来非常方便。但是,apiDoc也...
  • 一.apidoc说明 1.如何安装 前提:确保已安装node.js 使用npm进行apidoc安装&nbsp;&nbsp; node.js下载 npm install apidoc -g 2.如何使用 1)建立配置文件 分两种情况: ①已经有package.json文件 { "...
  • Springboot中使用apidoc生成接口文档

    万次阅读 2018-10-16 18:27:11
    为什么需要接口文档 当前后端分离时,需要前后端共同定义接口,编写接口文档。所以,在项目开发过程中需要有一个统一的文件进行沟通交流开发。 对开发人员而言,项目的维护和人员更迭,都需要文档来...apidoc。第一...
  • 曾经看过这样一个笑话:程序员最讨厌写文档,比这个还讨厌的...apidoc是一款可以由源代码中的注释直接自动生成api接口文档的工具,它几乎支持目前主流的所有风格的注释。 使用 首先你的环境必须要安装了node.js.然...
1 2 3 4 5 ... 20
收藏数 4,585
精华内容 1,834
关键字:

apidoc