apiDoc指南系列（二）
在上一篇文章中我们介绍了apiDoc的安装与简单使用，这篇文章我们继续讲解apiDoc的其他用法
Header
在使用API的过程中，我们不可避免的要用到Header，下面的示例代码展示了如何在apiDoc中描述Header。为了方便，我使用了python来进行编写，以及只展现了主要的代码部分，完整的代码请到gitlab上进行查看。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 |
""" @api {get} /user/articles 个人文章列表 @apiName GetUserOwnArticle @apiVersion 0.1.0 @apiGroup Article @apiHeader {String} Authorization JWT登录认证 @apiHeaderExample {json} Header-Example: { "Authorization": "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwOi8vY29vbGNvZGUuZGV2L2FwaS9sb2dpbi93ZWNoYXQiLCJpYXQiOjE0ODAyNDk0MzIsImV4cCI6MTQ4MzY1NzQzMiwibmJmIjoxNDgwMjQ5NDMyLCJqdGkiOiJLN3VDV05IeThmRFRBcVFXIiwic3ViIjo0fQ.W0ejklbilFdn--e4rZD5vlVczoryHLX1oNHYFKl07Ss" } @apiSuccess {Number} id 文章ID ...... @apiSuccess {Json} comments 评论 @apiSuccessExample Success-Response: ...... @apiUse TokenError """ |
在上面的代码中我们使用@apiHeader来描述Header信息，通过@apiHeaderExample来提供Header示例。这样我们就成功的把Header展示到apiDoc中了。
在apiDoc页面进行测试
一般我们在进行API调试的时候都是在postman插件中进行调试，但是apiDoc提供了一个能够直接在文档页面进行测试数据的方法。接下来我教给大家如何进行展示。
还记得项目根目录下的apidoc.json文件么，打开它，将下面的信息添加进去。
|
1 2 |
"sampleUrl": "http://coolcodeapi.wodetiku.com" |
这行文字的作用是apiDoc将会通过这个url来进行API测试，这样所有的API都会以这个url为前缀创建测试链接，并且还包含我们上面所说的Header，如果API文档设置有参数的话，参数也会一并显示出来。
但是如果某些路由不想进行在线测试的话也很简单，只需在相应的文档文件中加入下面的代码就可以了。
|
1 2 |
@apiSampleRequest off |
这样我们可以直接在API文档页面进行测试，而不用使用postman了。当然postman是一个十分强大的插件，而apiDoc只提供了最基础的内容，如果满足不了需求的话可以打开postman继续进行调试。