欢迎您访问程序员文章站本站旨在为大家提供分享程序员计算机编程知识!
您现在的位置是: 首页

使用apidoc 生成Api接口文档

程序员文章站 2024-02-15 21:38:52
...

前言:

在项目开发过程中,总会牵扯到接口文档的设计与编写,不管是使用word文档,还是git上markdown编写md文档,在界面显示上不够漂亮和直观,并且布局也花费很大的时间。apidoc是一个轻量级的在线接口文档生成系统,仅需要按照要求书写相关注释,就可以生成可读性好、界面美观的在线接口文档


一、apidoc的基本概念

apoDoc是从源码的注释中生成RestFul api 文档,样子还是蛮漂亮的……

1.1、我们选用JavaDoc-Style注释样式:
**
 1. @api {get} /user/:id Request User information
 2. @apiName GetUser
 3. @apiGroup User
 4.  5. @apiParam {Number} id Users unique ID.
 5.  7. @apiSuccess {String} firstname Firstname of the User.
 6. @apiSuccess {String} lastname  Lastname of the User.
 */
1.2、安装apiDoc
   1、apidoc是基于nodeJs平台,在安装apidoc之前,需要先安装nodeJs。
   2、npm install apidoc -g //全局安装apidoc
   3、apidoc -v命令,apidoc是否安装成功。 
1.3、常用的命令格式如下:
  apidoc -i myapp/ -o apidoc/  把myapp中的配置和注释生成到apidoc文件下
1.4、使用apidoc 生成Api接口文档
  1、创建开发文件夹src(或者自己定义名,命令编译的时候文件名写对就可以了)
       mkdir src
  2、创建代码文件夹的根目录
       mkdir Bschool
  3、每个根目录文件下创建apidoc.json文件。
         {
            "name": "B端学校", 
            "version": "1.0.0",
            "description": "B端学校->详情->具体详情页",
            "title": "AiJianZiPlatform",
            "url" : "后台http"
          }
   4、每个根目录文件下还需创建example.java文件
     /**
     * @api {POST} /province 获取省份
     * @apiGroup Bschool
     * @apiVersion 0.0.1
     * @apiDescription 用于B端学校获取学校的省份列表

     * @apiParam (Request Params) {String} [schoolId] 学校id

     * @apiSuccess (200) {String} msg 信息
     * @apiSuccess (200) {int} code 0 代表无错误 1代表有错误
     * @apiSuccessExample {json} 返回样例:
     *                {"code":"0","msg":"修改成功"}
     */
   5、apidoc -i 开发文件的路径 -o 生成文件的路径

      apidoc -i src/Bschool -o apidoc/Bschool
   6、打开项目文件夹下的index.html可以查看效果

二、apidoc的apidoc.json 和注释文件的注释都是什么含义

apidoc文档

  • 文件目录结果如下图所示。
    使用apidoc 生成Api接口文档
    文件解析:
     apidoc.json:apidoc的项目配置文件,文件名不可更改。
     {
        "name": "bSchool",     //项目名
        "version": "1.0.0",     //项目文档的版本号
        "description": "b端学校",    //详细描述
        "title": "bSchool",              //文档标题,显示在文档界面的最上方
        "url": "https://api.github.com/v1",  
        // 整个api url的前缀,接下来的所有接口url都会加上这个前缀。
        用来区分不同系统的api端口和api的ip前缀
     }
     bSchool.java:源文件,pidoc会搜索整个工程目录选择所有可能的源文件,  
                   可以建立好几个源文件。
  • apidoc参数(params)的书写

       1@api {请求的HTTP方法名}  url path [接口名]
            @api {POST} /province 获取省份
       2@apiDescription 具体的描述内容
            @apiDescription 用于B端学校获取学校的省份列表
       3@apiGroup name name不支持中文,一旦输入中文,  
              apidoc就会忽略这些中文字符。如果需要在界面中显示中文接口组名
            @apiGroup Bschool
       4@apiParam 请求参数类型。  
          例如 {Boolean}, {Number}, {String}, {Object}, {String[]}
            @apiParam [(group)] [{type}] [field=defaultValue] [description]
            @apiParam (Request Params) {String} [schoolId] 学校id
       5@apiSuccess
            @apiSuccess [(group)] [{type}] field [description]
            * @apiSuccess (200) {int} code 0 代表无错误 1代表有错误
       6@apiSampleRequest /province
          表示一个接口测试块,根据定义的请求参数来生成一个表单进行接口测试。