axios api文档 api文档系统

转载

mob64ca1413c518 2023-12-15 14:14:43

文章标签 axios api文档 API json 配置文件 文章分类 iOS 移动开发

简介：apidoc是一个轻量级的在线REST接口文档生成系统，支持多种主流语言，包括Java、C、C#、PHP和Javascript等。使用者仅需要按照要求书写相关注释，就可以生成可读性好、界面美观的在线接口文档。

1、安装

apidoc是基于nodeJs平台，在安装apidoc之前，需要先安装nodeJs和npm（安装步骤省略）。

进入命令行，输入npm install apidoc -g安装

2、使用

先介绍一下apidoc中的重要命令和参数：

apidoc的命令格式如下：　　apidoc 参数

参数    描述
-f    选择要解析的文件，支持正则表达式。-f参数可以使用多次，多个表达式可以对应不同的-f。如：apidoc -f ".*\.js$" -f ".*\\.ts$"
-i    选择源代码所在的位置。如：apidoc -i myapp/
-o    选择生成的目标文件所在的位置。如：apidoc -o apidoc/
-t    为生成文件选择模板，可以创建和使用自定义的模板。（笔者注：目前为止，笔者还没有使用过这个参数）
-h    跟绝大多数命令一样，这个参数可以打印出帮助文档

以下为本地测试目录

axios api文档 api文档系统_配置文件

apidoc.json：apidoc的项目级配置文件，它必须位于整个工程目录顶层。
Demo1.java：用于演示的demo源文件，它可以位于整个工程目录的顶层目录及其子目录下。apidoc会搜索整个工程目录选择所有可能的源文件。

apidoc.json

常用配置

配置名    描述
name    工程名。如果该字段不存在，则apidoc会尝试通过package.json（apidoc顶层配置文件）来生成
version    工程文档的版本号。如果该字段不存在，则apidoc会尝试通过package.json（apidoc顶层配置文件）来生成
description    工程详细描述。如果该字段不存在，则apidoc会尝试通过package.json（apidoc顶层配置文件）来生成
title    文档标题，显示在文档界面的最上方
url    整个api url的前缀，接下来的所有接口url都会加上这个前缀
sampleUrl    api示例的url前缀。如果设置了这个值，则界面中显示请求表单，可以用于测试接口
header    
title    文档头（header）的连接锚点名
filename    文档头所使用的文件
footer    
title    文档尾（footer）的连接锚点名
filename    文档尾所使用的文件
order    接口的排列顺序list，如果不指定，则由apidoc自行确定

示例：

{
  "name": "apidoc测试", 
  "version": "1.0.0",
  "description": "这是一个简单的apidoc的demo",
  "title": "demo",
  "url" : "https://api.github.com/v1"
}

Demo1.java

　常用注解：

@api 定义API的请求方法、路径和名字
@apiDescription 定义API的描述
@apiGroup 定义API的分组
@apiParam 定义API的参数
@apiParamExample 参数请求的事例
@apiVersion 版本
@apiErrorExample API错误示例
@apiSuccessExample API正常示例

示例

/**
     * @apiGroup Product
     * @api {GET} /product/{id}  查询一个产品
     * @apiDescription 指定产品id , 删除产品的全部信息，包括关联的schema
     * @apiParam {String} id 产品id(必填*)
     * @apiSuccessExample SuccessExample
     * HTTP/1.1 200
     * {
     * id: 'xxx',
     * modelId: 'xxxxx',
     * name: 'xxx',
     * intro: 'xxxx'
     * }
     * @apiErrorExample ErrorExample
     * HTTP/1.1 600
     * 具体的异常信息
     */
    @GetMapping("/{id}")
    public Product getOneProduct(@PathVariable String id)
    {
        return productServ.findOne(id);
    }