TBD 生成 API 文档(Generating API Documentation)
最后更新于:2022-04-01 04:01:30
# API documentation generator for Yii 2
This extension provides an API documentation generator for the [Yii framework 2.0](http://www.yiiframework.com/).
For license information check the [LICENSE](https://github.com/yiisoft/yii2-apidoc/blob/master/LICENSE.md)-file.
[![Latest Stable Version](https://camo.githubusercontent.com/164bda703f0198437f1b609d046ef25f1524a44c/68747470733a2f2f706f7365722e707567782e6f72672f796969736f66742f796969322d617069646f632f762f737461626c652e706e67)](https://packagist.org/packages/yiisoft/yii2-apidoc) [![Total Downloads](https://camo.githubusercontent.com/cdf07c2224b6981f16efe7ec4bd27137909ca836/68747470733a2f2f706f7365722e707567782e6f72672f796969736f66742f796969322d617069646f632f646f776e6c6f6164732e706e67)](https://packagist.org/packages/yiisoft/yii2-apidoc)
## [](https://github.com/yiisoft/yii2-apidoc#installation)Installation
The preferred way to install this extension is through [composer](http://getcomposer.org/download/).
Either run
~~~
php composer.phar require --prefer-dist yiisoft/yii2-apidoc
~~~
or add
~~~
"yiisoft/yii2-apidoc": "~2.0.0"
~~~
to the require section of your composer.json.
## [](https://github.com/yiisoft/yii2-apidoc#usage)Usage
This extension offers two commands:
* `api` to generate class API documentation.
* `guide` to render nice HTML pages from markdown files such as the yii guide.
Simple usage for stand alone class documentation:
~~~
vendor/bin/apidoc api source/directory ./output
~~~
Simple usage for stand alone guide documentation:
~~~
vendor/bin/apidoc guide source/docs ./output
~~~
You can combine them to generate class API and guide documentation in one place:
~~~
# generate API docs
vendor/bin/apidoc api source/directory ./output
# generate the guide (order is important to allow the guide to link to the apidoc)
vendor/bin/apidoc guide source/docs ./output
~~~
By default the `bootstrap` template will be used. You can choose a different template with the `--template=name` parameter. Currently there is only the `bootstrap` template available.
You may also add the `yii\apidoc\commands\ApiController` and `GuideController` to your console application command map and run them inside of your applications console app.
### [](https://github.com/yiisoft/yii2-apidoc#advanced-usage)Advanced usage
The following script can be used to generate API documentation and guide in different directories and also multiple guides in different languages (like it is done on yiiframework.com):
~~~
#!/bin/sh
# set these paths to match your environment
YII_PATH=~/dev/yiisoft/yii2
APIDOC_PATH=~/dev/yiisoft/yii2/extensions/apidoc
OUTPUT=yii2docs
cd $APIDOC_PATH
./apidoc api $YII_PATH/framework/,$YII_PATH/extensions $OUTPUT/api --guide=../guide-en --guidePrefix= --interactive=0
./apidoc guide $YII_PATH/docs/guide $OUTPUT/guide-en --apiDocs=../api --guidePrefix= --interactive=0
./apidoc guide $YII_PATH/docs/guide-ru $OUTPUT/guide-ru --apiDocs=../api --guidePrefix= --interactive=0
# repeat the last line for more languages
~~~
### [](https://github.com/yiisoft/yii2-apidoc#creating-a-pdf-of-the-guide)Creating a PDF of the guide
You need `pdflatex` and GNU `make` for this.
~~~
vendor/bin/apidoc guide source/docs ./output --template=pdf
cd ./output
make pdf
~~~
If all runs without errors the PDF will be `guide.pdf` in the `output` dir.
## [](https://github.com/yiisoft/yii2-apidoc#special-markdown-syntax)Special Markdown Syntax
We have a special Syntax for linking to classes in the API documentation. See the [code style guide](https://github.com/yiisoft/yii2/blob/master/docs/internals/core-code-style.md#markdown) for details.
## [](https://github.com/yiisoft/yii2-apidoc#creating-your-own-templates)Creating your own templates
TDB
## [](https://github.com/yiisoft/yii2-apidoc#using-the-model-layer)Using the model layer
TDB