后端开发之--APIdoc的应用

本文介绍如何利用ApiDoc工具简化后端API文档的编写过程,并通过具体示例展示了如何定义API组、版本及参数等关键信息。

摘要生成于 C知道 ,由 DeepSeek-R1 满血版支持, 前往体验 >

前言

最近在学习后端开发,而后端开发中写好Api文档是十分重要的一部分,所以写下这篇博客,一个是推荐ApiDoc这个工具,另一个是加深自己对其的理解。

链接

这里是官网

解析一

全局安装apidoc
npm install apidoc -g

创建一个文件夹如myapp  新建文件example.js文件

example.js

var currentUser = {
    name: 'Mary'
};

/**
*@api{post}/user Post User information
*@apiName PostUser
*@apiGroup User
*
*@apiSuccess {String} name The users name
*
*@apiSuccessExample Example data on success:
*{
* name:'Paul'
*}
*/
function getUser() {
    return {code: 200, data: currentUser };
}

function setName(name) {
    if (name.length === 0) {
        return {code:404, message:'NameEmptyError'};
    }
    currentUser.name = name;
    return {code: 204};
}
在当前目录运行命令 apidoc
出现: info:Done后,
点开当前目录生成的doc文件,运行index.html即可

效果图:

这里写图片描述

解析二

根文件夹新建文件_apidoc.js
测试版本比较功能
这个功能实际的作为:
如果你要修改一个API文档,你可以把老的API放到_apidoc.js中,然后尽情修改你新的api,
大家也能够看到你修改的地方

_apidoc.js

/**
*@api{post}/user Post User information
*@apiName PostUser
*@apiGroup User
*@apiVersion 0.1.0
*
*@apiSuccess {String} name The users name
*
*@apiSuccessExample Example data on success:
*{
* name:'Paul'
*}
*/

example.js

var currentUser = {
    name: 'Mary'
};

/**
*@api{post}/user Post User information
*@apiName PostUser
*@apiGroup User
*@apiVersion 0.2.0
*
*@apiSuccess {Number} age Calculated age from Birthday
*
*@apiSuccessExample Example data on success:
*{
* name:'Paul'
* age:27
*}
*/
function getUser() {
    return {code: 200, data: currentUser };
}

function setName(name) {
    if (name.length === 0) {
        return {code:404, message:'NameEmptyError'};
    }
    currentUser.name = name;
    return {code: 204};
}

效果图
这里写图片描述

到这里我们应该对apiDoc有一定的了解了,
官网中给出19中关于apiDoc的参数,即@之后的变量。
这里我们以实际例子挑几种讲一下~ 能够写出一份好看的Api文档就行了,剩下的根据需求再看~
@apiGroup
@apiVersion
@api 方法, 路由, api名称
@apiDescription
@apiParam {参数类型} 参数名 参数描述
@apiSuccess {参数类型} 参数名 参数描述
@apiSuccessExample
@apiError

example.js

/**
*@apiGroup ApiGroupName
*@apiVersion 0.1.0
*@api {get} /user/:id this is the apiName
*@apiDescription This is the Api Description.
*@apiParam {String} id id of the user
*@apiSuccess {String} firstname Firstname of the User.
*@apiSuccessExample {json} Success-Response:
*                   { "content": "This is an example content" }
*@apiError UserNotFound The <code>id</code> of the User was not found.
*/

效果图:
这里写图片描述

评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值