Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/pahanini/yii2-rest-doc
Yii2 REST doc generator
https://github.com/pahanini/yii2-rest-doc
documentation generator rest-api slate yii2
Last synced: about 1 month ago
JSON representation
Yii2 REST doc generator
- Host: GitHub
- URL: https://github.com/pahanini/yii2-rest-doc
- Owner: pahanini
- Created: 2015-04-10T06:11:05.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2020-09-15T18:40:45.000Z (over 4 years ago)
- Last Synced: 2024-10-06T14:35:32.724Z (3 months ago)
- Topics: documentation, generator, rest-api, slate, yii2
- Language: PHP
- Homepage:
- Size: 137 KB
- Stars: 36
- Watchers: 7
- Forks: 19
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Yii2 Rest Controller Documentator
[](https://travis-ci.org/pahanini/yii2-rest-doc)
[](https://styleci.io/repos/33711749)
[](https://packagist.org/packages/pahanini/yii2-rest-doc)
[](https://packagist.org/packages/pahanini/yii2-rest-doc)
[](https://packagist.org/packages/pahanini/yii2-rest-doc)
[](https://packagist.org/packages/pahanini/yii2-rest-doc)
## About
Create precise documentation to your Yii2 API [REST](http://www.yiiframework.com/doc-2.0/guide-rest-quick-start.html)
controllers. Library parses your code and generates objects with meta data that could be used with any template
engine to generate great API docs.
You do not need to edit documentation when you change you code. Just rebuild you docs with this tool.
## Install
- Add `"pahanini/yii2-rest-doc": "*"` to required section of your composer.json
- Add to your console application config
``` php
'controllerMap' => [
'build-rest-doc' => [
'sourceDirs' => [
'@frontend\controllers\rest', // <-- path to your API controllers
],
'template' => '//restdoc/restdoc.twig',
'class' => '\pahanini\restdoc\controllers\BuildController',
'sortProperty' => 'shortDescription', // <-- default value (how controllers will be sorted)
'targetFile' => 'path/to/nice-documentation.html'
],
]
```
## Template example (twig)
``` html
{% for controller in controllers %}
{{ controller.shortDescription }}
{{ controller.longDescription }}
{% if controller.hasLabel('authenticated') %}
Require login and password!
{% endif %}
List of supported actions:
- {{ action }}
{% for action in controller.actions %}
{% endfor %}
Get params available for index action:
-
{{ item.variableName }} - {{ item.description }}, default - {{ item.defaultValue }}
{% for item in controller.query %}
{% endfor %}
Model fields:
Name
Type
Description
Can be updated?
{% for item in controller.model.fields %}
{{ item.name }}
{{ item.type }}
{{ item.description }}
{{ item.isInScenario('api-update') ? 'yes' : 'no' }}
{% endfor %}
{% endfor %}
```
## Data available in template
List of data automatically extracted from code:
- controller name
- action's of each controller
- model fields
- extra fields
- model rules (TBD)
List of special tags:
- short and long description of controller
- query tags
Inheritance is also supported. Use `@inherited` or `@inheritdoc` tags.
### Controller
- `@restdoc-ignore` - skip controller.
- `@restdoc-label name` - mark controller with label. Label name available via `controller.hasLabel('labelName')` in template
- `@restdoc-query name=false Name of part of name to find users` - query params with description.
### Model
To describe model's fields you can use two approaches.
#### Link to property tag.
If you already have phpDocumentator `@property` tag you can use it to describe API field.
Model's doc block example:
```php
/**
* My model.
*
* @property string $title Model's title
*/
```
* `@restdoc-link $title` - use `$title` property to describe `$title` api field
* `@restdoc-link title $model_title` - use `$title` property to describe `$model_title` api field
### Separate field description
If you do not have `@property` tag or API field is not directly connected with property use `@restdoc-field` tag.
Example:
```php
/**
* @restdoc-field int $id ID
* @restdoc-field string $title Model's title
*/
```
### Extra fields
Use @restdoc-extraField and @restdoc-extraLink for extra fields.
### Sort fields
Use @restdoc-sortField to sort field according to your code.
### Skip fields
Use @restdoc-ignore to skip field.
```php
/**
* @restdoc-ignore $hidden
*/
```
## Integrate With Slate
[Slate](https://github.com/tripit/slate) is probably one of the best tools to generate nice API. So you can
use this tool to create index.md file for slate. You can use on afterAction event to automatically start slate.
Example:
``` php
'controllerMap' => [
'build-rest-doc' => [
'sourceDirs' => [
'@frontend\controllers\rest',
],
'template' => '//restdoc/restdoc.twig',
'class' => '\pahanini\restdoc\controllers\BuildController',
'targetFile' => 'path/to/slate/index.md',
'on afterAction' => function() { exec("bundle exec middleman build") }
],
]
```
## Rationale
Creating of Yii2 controllers is an easy task, but supporting of documentation in actual state is often boring
and tough challenge. Using automatic tool like [phpDocumentator](https://github.com/phpDocumentor/phpDocumentor2)
or [swagger](http://swagger.io/) makes life easier but its still require to describe all models fields
and rules using tags or comments.
In other hand Yii2 controllers and models keep a lot of information about internal structure like actions,
field names, scenarios for update and insert operations. This package extracts such an information from
REST controllers and models and using this data along with phpdocumentator tags automatically generates
index.md for [slate](https://github.com/tripit/slate) or any other documentation file.