您将要创造的
在本 使用Yii2编程系列中 ，我指导读者使用PHP的Yii2框架。 您可能还对我 的Yii Framework简介 感兴趣 ，它 介绍了Yii 的好处，并概述了Yii 2.x的新增功能。
欢迎！ 最近，我写了关于为您的Yii应用程序构建REST API以及为我们的启动系列应用程序Meeting Planner 扩展了自定义API的文章 。
在今天的教程中，我将向您介绍Yii的apidoc扩展 ，该扩展会自动为您的代码生成可浏览的文档。 我将使用它来为Meeting Planner生成API文档。
入门
安装apidoc很容易。 如上所示，您只需使用composer添加软件包。
除了从代码生成文档之外，它还能够从markdown生成文档并将其转换为PDF。
例如，有Yii Framework文档 ，典型的代码文档：
并且，这是Yii2指南 ，我相信它是从这里的markdown生成的，并与代码文档集成在一起以便于浏览：
这是apidoc支持的文档语法 ； 它基于phpdoc 。
具有讽刺意味的是，apidoc的文档尚未完成，但对于基本的自动文档而言，它相当容易使用。
生成API文档
如果您已经遵循了我的启动系列文章 ，那么您会知道我正在构建一个广泛的API以支持移动应用程序等。Apidoc是我为其维护动态自动化文档的理想方式。
当然，还有许多其他Web服务可以帮助您记录API，但是我发现Yii的apidoc可以很好地满足我的需求，并且我赞赏它们使用的phpdoc风格的主题。
如果我希望使用标准的注释样式，则其他服务很可能可以通过Meeting Planner代码轻松地构建文档。
创建评论块
基本上，您可以在apidoc用于构建文档的代码中创建注释。 它在Yii编码风格指南中进行了描述。
您可以在每个文件的顶部放置一个注释块，如下所示：
然后在每个控制器或模型定义上方放置一个注释块：
/**
* UserTokenController provides API functionality for registration, delete and verify
*
* @author Jeff Reifman
* @since 0.1
*/
class UserTokenController extends Controller
{ 然后，在每个方法上方放置一个详细的注释块，其中包括参数，返回值和异常：
/**
* Register a new user with an external social Oauth_token
*
* @param string $signature the hash generated with app_secret
* @param string $app_id in header, the shared secret application id
* @param string $email in header, email address
* @param string $firstname in header, first name
* @param string $lastname in header, last name
* @param string $oauth_token in header, the token returned from Facebook during OAuth for this user
* @param string $source in header, the source that the $oauth_token is from e.g. 'facebook' e.g. [$oauth_token]
* @return obj $identityObj with user_id and user_token
* @throws Exception not yet implemented
*/
public function actionRegister($signature,$app_id='',$email='',$firstname ='',$lastname='',$oauth_token='',$source='') {您必须按照所述的规定布局成功地喂入apidoc。
使用占位符参数获取API文档
Yii团队开发了apidoc来生成代码文档。 但是，正如我在“ 保护您的API”中所写的那样，除哈希签名参数以外的所有参数都已移至http标头。 这些对apidoc不可见。 因此，为了生成API文档，我决定使用一种解决方法。
如您所见，我在方法中包含伪参数，然后在注释中指定将它们作为标题或“在标题中”发送。
* @param string $signature the hash generated with app_secret
* @param string $app_id in header, the shared secret application id
* @param string $email in header, email address
* @param string $firstname in header, first name
* @param string $lastname in header, last name只要函数定义中包含默认值，就不会造成真正的危害：
public function actionRegister($signature,$app_id='',$email='',$firstname ='',
$lastname='',$oauth_token='',$source='') {稍后，您将了解它通常如何用于API文档，即使它不是最佳的编码样式也是如此。
让我们继续实际使用apidoc生成文档。
生成文档
您可以通过不带参数的方式运行来查看apidoc命令：
$ ./vendor/bin/apidoc
This is Yii version 2.0.10.
The following commands are available:
- api Generate class API documentation.
api/index (default) Renders API documentation files
- guide This command can render documentation stored as
markdown files such as the yii guide
guide/index (default) Renders API documentation files
- help Provides help information about console commands.
help/index (default) Displays available commands or the detailed
information
To see the help of each command, enter:
apidoc help 我将使用api选项，这是您可以进行的配置：
$ ./vendor/bin/apidoc help api
DESCRIPTION
Renders API documentation files
USAGE
apidoc api [...options...]
- sourceDirs (required): array
$sourceDirs
- targetDir (required): string
$targetDir
OPTIONS
--appconfig: string
custom application configuration file path.
If not set, default application configuration is used.
--color: boolean, 0 or 1
whether to enable ANSI color in the output.
If not set, ANSI color will only be enabled for terminals that support it.
--exclude: string|array
files to exclude.
--guide: string
url to where the guide files are located
--guidePrefix: string (defaults to 'guide-')
prefix to prepend to all guide file names.
--help, -h: boolean, 0 or 1
whether to display help information about current command.
--interactive: boolean, 0 or 1 (defaults to 1)
whether to run the command interactively.
--pageTitle: string
page title
--template: string (defaults to 'bootstrap')
template to use for rendering 为了生成我的API文档，该文档的目录也是api ，我将执行以下操作：
$ ./vendor/bin/apidoc api api api/web/docs
--pageTitle=MeetingPlanner
TargetDirectory already exists. Overwrite? (yes|no) [yes]:yes
Searching files to process... done.
Loading apidoc data from cache... done.
Checking for updated files... done.
8 files to update.
Processing files... done.
Updating cross references and backlinks... done.
Rendering files: done.
generating extension index files...done.
generating search index...done.
35 errors have been logged to api/web/docs/errors.txt
214 warnings have been logged to api/web/docs/warnings.txt因为我还没有完成对整个树的注释，所以会生成错误和警告。 他们通常看起来像这样：
Array
(
[0] => Array
(
[line] => 31
[file] => api/controllers/ParticipantController.php
[message] => Method behaviors has no parent to inherit from in api\controllers\ParticipantController.
)
[1] => Array
(
[line] => 32
[file] => api/controllers/PlaceController.php
[message] => Method behaviors has no parent to inherit from in api\controllers\PlaceController.
)浏览文档
将上述apidoc命令行中的文档发布到/api/web/docs意味着您可以从Web 浏览Meeting Planner文档 。
例如，这是UserTokenController ：
这是actionRegister（）方法，显示带有in header信息的参数注释。
这是MeetingController文档 ：
并且，这是actionMeetingplacechoices（）方法 ：
如您所见，这对于在交付代码时实时与第三方程序员共享API极为有用。 最大的好处是，它消除了分别手动维护API文档的需要。
每当您可以取消启动公司的任务时，这都是巨大的胜利。
展望未来
希望您已经了解了Yii2 apidoc扩展的功能。 您可以使用它来维护所有代码的文档，还可以鼓励您紧跟注释，我将在以后做更多的工作。
如果您有任何问题或反馈，请在评论中发布。 如果您想了解我将来的Envato Tuts +教程和其他系列，请访问我的讲师页面或关注@reifman 。 一定要检查一下我的启动系列和Meeting Planner 。
相关链接
- Yii2 API文件（GitHub）
- 使用Yii2编程：构建RESTful API（Envato Tuts +）
- 使用PHP构建启动：构建RESTful API（Envato Tuts +）
- Yii2开发人员交流
翻译自: https://code.tutsplus.com/tutorials/programming-with-yii-generating-documentation--cms-27899