apiDoc 详解 api接口文档生成
PHP使用apiDocapi接口文档安装apidoc配置(apidoc.json)apidoc.json配置项apidoc注释参数@api@apiErrorExample@apiDefine@apiDeprecated@apiDescription@apiError@apiExample@apiGroup@apiParam@apiHeader@apiHeaderExample@apiIgnore@apiName@apiParamExample@apiPermission@apiPrivate@apiSampleRequest@apiSuccess@apiSuccessExample@apiUse@apiVersion生成接口文档安装apidoc官网
通过npm安装，请提前安装好npm
可以通过以下命令安装apidoc:
npminstallapidoc-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浏览器标题urlapi路径前缀例如:https://api.github.com/v1sampleUrl如果设置了该参数，那么在文档中便可以看到用于测试接口的一个表单(详情可以查看参数@apiSampleReques)header.title页眉导航标题header.filename页眉文件名(markdown)footer.title页脚导航标题footer.filename页脚文件名(markdown)order接口名称或接口组名称的排序列表如果未定义，那么所有名称会自动排序"order":["Error","Define","PostTitleAndError",PostError"]更多详情
apidoc注释参数@api【必填字段】否则，apidoc会忽略该条注释
@api{method}path[title]参数列表:
参数必填描述methodyes请求类型:DELETE,GET,POST,PUT,...更多pathyes请求路径titleno接口标题例：
/***@api{get}/user/getUserById/:id获取用户数据-根据id*/@apiErrorExample接口错误返回示例(格式化输出)
@apiErrorExample[{type}][title]example参数列表:
参数必填描述typeno响应类型titleno示例标题exampleyes示例详情(兼容多行)例：
/***@api{get}/user/getUserById/:id获取用户数据-根据id*@apiErrorExample{json}Error-Response:*HTTP/1.1404NotFound*{*"error":"UserNotFound"*}*/@apiDefine定义注释模块(类似于代码中定义一个常量)，对于一些通用可复用的注释模块(例如:接口错误响应模块),只需要在源代码中定义一次，便可以在其他注释模块中随便引用，最后在文档导出时会自动替换所引用的注释模块，定义之后您可以通过@apiUse来引入所定义的注释模块。(注:可以同时使用@apiVersion来定义注释模块的版本)
@apiDefinename[title][description]参数列表:
参数必填描述nameyes注释模块名称(唯一)，不同@apiVersion可以定义相同名称的注释模块titleno注释模块标题descriptionno注释模块详细描述(详细描述另起一行，可包含多行)例：
/***@apiDefineFailResponse*@apiErrorExampleResponse(fail):*{*"code":"error"*"error_message":"错误内容"*}*//***@apiDefineSuccessResponse*@apiSuccessExampleResponse(success):*{*"code":"0"*"error_message":""*"data":"内容"*}*//***@apiUseSuccessResponse**@apiUseFailResponse*/@apiDeprecated标注一个接口已经被弃用
@apiDeprecated[text]参数列表:
参数必填描述textyes多行文字描述例：
/***@apiDeprecatedusenow(#Group:Name).**Example:tosetalinktotheGetDetailsmethodofyourgroupUser*write(#User:GetDetails)*/@apiDescriptionapi接口的详细描述
@apiDescription[text]参数列表:
参数必填描述textyes多行文字描述例：
/***@apiDescriptionThisistheDescription.*Itismultilinecapable.**LastlineofDescription.*/@apiError错误返回参数
@apiError[(group)][{type}]field[description]参数列表:
参数必填描述(group)no所有的参数都会通过这个参数进行分组，如果未设置，默认值为Error4xx{type}no返回类型，例如{Boolean}，{Number}，{String}，{Object}，{String[]}（字符串数组），…fieldyes返回iddescriptionno参数描述例：
/***@api{get}/user/getUserById/:id获取用户数据-根据id*@apiErrorUserNotFoundTheidoftheUserwasnotfound.*//***@apiError(错误分组){Object}xxxxxxxxxxx*/@apiExample接口方式请求示例
@apiExample[{type}]titleexample参数列表:
参数必填描述typeno请求内容格式titleyes示例标题exampleyes示例详情(兼容多行)例：
/***@api{get}/user/getUserById/:id*@apiExample{curl}Exampleusage:*curl-ihttp://127.0.0.1/user/getUserById/1*/@apiGroup定义接口所属的接口组，虽然接口定义里不需要这个参数，但是您应该在每个接口注释里都添加这个参数，因为导出的接口文档会以接口组的形式导航展示。
@apiGroupname参数列表:
参数必填描述nameyes接口组名称(用于导航,不支持中文)例：
/***@apiDefineUser用户信息*//***@api{get}/user/getUserById/:id*@apiGroupUser*/@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”fieldyes参数名称(定义该请求体参数为必填)[field]yes参数名称(定义该请求体参数为可选)=defaultValueno参数默认值descriptionno参数描述例：
/***@api{get}/user/getUserById/:id*@apiParam{Number}idUsersuniqueID.*//***@api{post}/user/*@apiParam{String}[firstname]OptionalFirstnameoftheUser.*@apiParam{String}lastnameMandatoryLastname.*@apiParam{String}country="DE"Mandatorywithdefaultvalue"DE".*@apiParam{Number}[age=18]OptionalAgewithdefault18.**@apiParam(Login){String}passOnlyloggedinuserscanpostthis.*Ingenerateddocumentationaseparate*"Login"Blockwillbegenerated.*/@apiHeader描述接口请求头部需要的参数(功能类似@apiParam)
@apiHeader[(group)][{type}][field=defaultValue][description]参数列表:
参数必填描述(group)no所有的参数都会以该参数值进行分组(默认Parameter){type}no返回类型(例如:{Boolean},{Number},{String},{Object},{String[]})fieldyes参数名称(定义该头部参数为必填)[field]yes参数名称(定义该头部参数为可选)=defaultValueno参数默认值descriptionno参数描述例：
/***@api{get}/user/getUserById/:id*@apiHeader{String}access-keyUsersuniqueaccess-key.*/@apiHeaderExample请求头部参数示例
@apiHeaderExample[{type}][title]example参数列表:
参数必填描述typeno请求内容格式titleno请求示例标题exampleyes请求示例详情(兼容多行)例：
/***@api{get}/user/getUserById/:id*@apiHeaderExample{json}Header-Example:*{*"Accept-Encoding":"Accept-Encoding:gzip,deflate"*}*/@apiIgnore如果你需要使用该参数，请把它放到注释块的最前面。如果设置了该参数，那么该注释模块将不会被解析(当有些接口还未完成或未投入使用时，可以使用该字段)
@apiIgnore[hint]参数列表:
参数必填描述hintno描接口忽略原因描述例：
/***@apiIgnoreNotfinishedMethod*@api{get}/user/getUserById/:id*/@apiName接口名称，每一个接口注释里都应该添加该字段，在导出的接口文档里会已该字段值作为导航子标题，如果两个接口的@apiVersion和@apiName一样，那么有一个接口的注释将会被覆盖(接口文档里不会展示)
@apiNamename参数列表:
参数必填描述nameyes接口名称(相同接口版本下所有接口名称应该是唯一的)例：
/***@api{get}/user/getUserById/:id*@apiNamegetUserById*/@apiParamExample请求体参数示例
@apiParamExample[{type}][title]example参数列表:
参数必填描述typeno请求内容格式titleno请求示例标题exampleyes请求示例详情(兼容多行)例：
/***@api{get}/user/getUserById/:id*@apiParamExample{json}Request-Example:*{*"id":1*}*/@apiPermission允许访问该接口的角色名称
@apiPermissionname参数列表:
参数必填描述nameyes允许访问的角色名称(唯一)例：
/***@api{get}/user/getUserById/:id*@apiPermissionnone*/@apiPrivate定义私有接口，对于定义为私有的接口，可以在生成接口文档的时候，通过在命令行中设置参数--privatefalse|true来决定导出的文档中是否包含私有接口
@apiPrivate例：
/***@api{get}/user/getUserById/:id*@apiPrivate*/@apiSampleRequest设置了该参数后，导出的html接口文档中会包含模拟接口请求的form表单；如果在配置文件apidoc.json中设置了参数sampleUrl,那么导出的文档中每一个接口都会包含模拟接口请求的form表单，如果既设置了sampleUrl参数，同时也不希望当前这个接口不包含模拟接口请求的form表单，可以使用@apiSampleRequestoff来关闭。
@apiSampleRequesturl参数列表:
参数必填描述urlyes模拟接口请求的url@apiSampleRequesthttp://www.example.com意为覆盖apidoc.json中的sampleUrl参数@apiSampleRequestoff意为关闭接口测试功能例：发送测试请求到: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*@apiSampleRequesthttp://test.github.com/some_path/*/关闭接口测试功能
/***@api{get}/user/getUserById/:id*@apiSampleRequestoff*/发送测试请求到http://api.github.com/some_path/user/getUserById/:id(由于没有设置apidoc.json中的sampleUrl参数，所以只有当前接口有模拟测试功能)
/***@api{get}/user/getUserById/:id*@apiSampleRequesthttp://api.github.com/some_path/*/@apiSuccess接口成功返回参数
@apiSuccess[(group)][{type}]field[description]参数列表:
参数必填描述(group)no所有的参数都会以该参数值进行分组,默认值:Success200{type}no返回类型(例如:{Boolean},{Number},{String},{Object},{String[]})fieldyes返回值(返回成功码)=defaultValueno参数默认值descriptionno参数描述例：
/***@api{get}/user/getUserById/:id*@apiSuccess{String}firstnameFirstnameoftheUser.*@apiSuccess{String}lastnameLastnameoftheUser.*/包含(group):
/***@api{get}/user/getUserById/:id*@apiSuccess(200){String}firstnameFirstnameoftheUser.*@apiSuccess(200){String}lastnameLastnameoftheUser.*/返回参数中有对象:
/***@api{get}/user/getUserById/:id*@apiSuccess{Boolean}activeSpecifyiftheaccountisactive.*@apiSuccess{Object}profileUserprofileinformation.*@apiSuccess{Number}profile.ageUsersage.*@apiSuccess{String}profile.imageAvatar-Image.*/返回参数中有数组：
/***@api{get}/users*@apiSuccess{Object[]}profilesListofuserprofiles.*@apiSuccess{Number}profiles.ageUsersage.*@apiSuccess{String}profiles.imageAvatar-Image.*/@apiSuccessExample返回成功示例
@apiSuccessExample[{type}][title]example参数列表:
参数必填描述typeno返回内容格式titleno返回示例标题exampleyes返回示例详情(兼容多行)例：
/***@api{get}/user/getUserById/:id*@apiSuccessExample{json}Success-Response:*HTTP/1.1200OK*{*"code":"0"*"message":""*"data":"加密内容"*}*/@apiUse引入注释模块，如果当前模块定义了@apiVersion,那么版本相同或版本最近的注释模块会被引入
@apiUsename参数列表:
参数必填描述nameyes引入注释模块的名称例：
/***@apiDefineMySuccess*@apiSuccess{string}firstnameTheusersfirstname.*@apiSuccess{number}ageTheusersage.*//***@api{get}/user/getUserById/:id*@apiUseMySuccess*/@apiVersion定义接口/注释模块版本
@apiVersionversion参数列表:
参数必填描述versionyes版本号(支持APR版本规则:major.minor.patch)例：
/***@api{get}/user/getUserById/:id*@apiVersion1.6.2*/小诀窍，笔者把接口中的通用部分利用apiDefine摘出来，放在一个公共文件中，之后可以利用apiUse去调用，或许部分注释参数可以直接使用apiDefine即可调用。
生成接口文档当然你注释参数写好了之后它也不会帮你自动生成，你需要自己运行以下命令：例：
apidoc-f".*\.php$"-i./application-o./public/apidoc参数列表:
参数描述-h,--help查看帮助文档-f--file-filters指定读取文件的文件名过滤正则表达式(可指定多个)例如:apidoc-f“.*.js"−f".∗.ts"-f".*\.ts"−f".∗.ts”意为只读取后缀名为js和ts的文件默认值:.clj.cls.coffee.cpp.cs.dart.erl.exs?.go.groovy.ino?.java.js.jsx.kt.litcoffeelua.p.php?.pl.pm.py.rb.scala.ts.vue-e--exclude-filters指定不读取的文件名过滤正则表达式(可指定多个)例如:apidoc-e“.*.js$”意为不读取后缀名为js的文件默认:’’-i,--input指定读取源文件的目录例如：apidoc-imyapp/意为读取myapp/目录下面的源文件默认值:./-o,--output指定输出文档的目录例如：apidoc-odoc/意为输出文档到doc目录下默认值:./doc/-t,--template指定输出的模板文件例如:apidoc-tmytemplate/默认:path.join(__dirname,‘…/template/’)(使用默认模板)-c,--config指定包含配置文件(apidoc.json)的目录例如:apidoc-cconfig/默认:./-p,--private输出的文档中是否包含私有api例如:apidoc-ptrue默认:false-v,--verbose是否输出详细的debug信息例如:apidoc-vtrue默认:false之后你就能通过浏览器进行访问了，比如我的是http://localhost/apidoc
在线生成接口文档
接口文档是项目开发中必需的说明文档，接口文档编写有很多不同的方式，今天本文简单介绍一下常用的几种接口文档编写方法。
API文档导入生成
使用接口文档工具Eolink演示API文档导入生成的过程。Eolink系统提供一键导入Swagger、Postman、RAP、YAPI等产品数据的功能。实现无负担从其他平台进行数据迁移。
在项目详情页点击左侧API功能，进入API管理页面，直接点击下拉框选择导入API。
配置导入规则：
选项说明：
将API导入到以下分组：选择对应的API分组
将新生成的API文档状态设置为：可以将导入API文档设置对应状态
将发生变更的API文档状态设置为：对已发生变更状态的API文档，可以更新指定的文档状态
将新生成的或发生变更的API文档的版本号设置为：可以将导入API文档设置指定的API版本号
设置好导入配置规则后，点击确定会显示成功提示，并在右侧栏显示我的任务队列进行中，当状态显示完成就导入成功了。
如下图：
刷新界面就可导入API数据：
自动生成文档
通过使用接口文档工具Eolink演示如何自动生成文档。
用户可以实现给项目关联的Swaqger生成的JSON文件地址，Eolink的API研发管理平台就能够远程读取SwaggerJSON文件地址并自动生成API文档。
进入API管理与测试，选择项目，左侧栏的其他可以看到API文档生成。
添加来源，在弹窗中选择通过SwaggerURL生成API文档，然后点击下一步：
输入Swagger生成的JSON地址，注意该JSON地址需要能够通过网络访问，并且该地址返回的数据需要是JSON类型的数据，否则会提示无法访问该地址。
配置完成后，界面会提示配置完成。此时您可以通过当前页面点击同步按钮，或通过OpenAPI触发同步操作。
使用APIFactory产品根据数据库生成API文档
APIFactory（API快速生成工厂）能够帮助用户直接从各种常见关系数据库、NoSQL数据库、大数据库中间件中生成统一格式的HTTPRestfulAPI。通过APIFactory，您可以通过编写SQL脚本或通过UI方式直接创建一个高性能的数据库操作API。
以上三种方法是生成API文档最常见的方法，通过使用一款好用的接口文档工具实现API文档导入生成、自动生成API文档，以及使用APIFactory产品数据库生成API文档，让开发在书写文档过程中不再痛苦，提高前后端的开发效率。
这里推荐上图做演示的这款接口文档工具，Eolink，它能设计、管理API，一键生成API文档，除此之外还能直接打通接口测试，一键发起API测试，方便快捷且功能强大。如有兴趣可自行试用：www.eolink.com