() translation by (you can also view the original English article)
En esta Serie de Programación con Yii2, estoy guiando a los lectores en el uso de Yii2 Framework para PHP. Quizás también estés interesado en mi Introducción a Yii Framework, comentarios sobre los beneficios de Yii y que incluye un resumen de lo que es nuevo en Yii 2.x.
¡Bienvenido! Recientemente, escribí sobre la Construcción de REST APIs para su Aplicación Yii y Ampliado la Serie API Personalizadas para usar en nuestro startup Aplicación, Meeting Planner.
En el tutorial de hoy, te introduzco a la Extensión de apidoc de Yii, que genera automáticamente documentación navegable su código. Voy a utilizar para generar documentación de la API para el Meeting Planner.
Para Empezar
Apidoc la instalación es fácil. Como se muestra arriba, usted apenas agrega el paquete con el compositor.
Además de generar documentación de código, también es capaz de generar la documentación de descuento y transformando esto en PDF.
Por ejemplo, hay esta la Documentación de Yii Framework, la documentación de códigos típicos:
Y aquí está la Guía de Yii2, que creo que es generado de descuento aquí e integrado con la documentación de código para la fácil navegación:
Aquí está la documentación sintaxis que admite apidoc; se basa en phpdoc.
Irónicamente, la documentación de apidoc aún no está completa, pero es bastante fácil de usar para auto-documentación básica.
Generando Documentación de la API
Si usted ha seguido junto la serie mi startup, eres consciente de que estoy construyendo una amplia API para soporte de aplicaciones móviles, etcetera. Apidoc es lo ideal para mí mantener dinámica documentación automatizada para él.
Sin duda hay un montón de otros servicios de web que ayudará a documentar su API, pero encontré que apidoc de Yii funcionó bien para mis necesidades, y aprecié el tema phpdoc-estilo que usan.
Usando un estándar estilo comentando es probable que sean capaces de construir fácilmente documentación de código Meeting Planner si alguna vez quiero utilizarlos otros servicios.
Crear Bloques de Comentario
Básicamente, crea comentarios dentro del código que apidoc utiliza para generar la documentación. Se describe en la Guía de estilo codificación de Yii.
Coloque un bloque de comentario en la parte superior de cada archivo como este:
1 |
<?php
|
2 |
/**
|
3 |
* @link https://meetingplanner.io
|
4 |
* @copyright Copyright (c) 2016 Lookahead Consulting
|
5 |
* @license https://github.com/newscloud/mp/blob/master/LICENSE
|
6 |
*/
|
Y coloque un bloque de comentario sobre cada controlador o la determinación del modelo:
1 |
/**
|
2 |
* UserTokenController provides API functionality for registration, delete and verify
|
3 |
*
|
4 |
* @author Jeff Reifman <jeff@meetingplanner.io>
|
5 |
* @since 0.1
|
6 |
*/
|
7 |
class UserTokenController extends Controller |
8 |
{
|
Luego, coloque un bloque de comentario detallado sobre cada método, que incluye parámetros, valores devueltos y excepciones:
1 |
/**
|
2 |
* Register a new user with an external social Oauth_token
|
3 |
*
|
4 |
* @param string $signature the hash generated with app_secret
|
5 |
* @param string $app_id in header, the shared secret application id
|
6 |
* @param string $email in header, email address
|
7 |
* @param string $firstname in header, first name
|
8 |
* @param string $lastname in header, last name
|
9 |
* @param string $oauth_token in header, the token returned from Facebook during OAuth for this user
|
10 |
* @param string $source in header, the source that the $oauth_token is from e.g. 'facebook' e.g. [$oauth_token]
|
11 |
* @return obj $identityObj with user_id and user_token
|
12 |
* @throws Exception not yet implemented
|
13 |
*/
|
14 |
public function actionRegister($signature,$app_id='',$email='',$firstname ='',$lastname='',$oauth_token='',$source='') { |
Debe seguir la disposición prescrita tal como se describe para alimentar apidoc con éxito.
Utilizando Argumentos de Marcador de Posición Para la Documentación API
El equipo de Yii desarrolló apidoc para generar documentación de código. Sin embargo, como escribí en Asegurar su API, todos menos el argumento de la firma de hash se ha movido a las cabeceras http. Estos son invisibles para la apidoc. Así, para generar documentación de la API, decidí utilizar una solución alternativa.
Como se puede ver, incluyen argumentos dummy en los métodos y luego especificar en los comentarios que éstos son enviados como cabeceras o "en header."
1 |
* @param string $signature the hash generated with app_secret |
2 |
* @param string $app_id in header, the shared secret application id |
3 |
* @param string $email in header, email address |
4 |
* @param string $firstname in header, first name |
5 |
* @param string $lastname in header, last name |
Como valores por defecto se incluyen en las definiciones de función, no hay ningún daño real hecho:
1 |
public function actionRegister($signature,$app_id='',$email='',$firstname ='', |
2 |
$lastname='',$oauth_token='',$source='') { |
En un momento, verás cómo esto funciona generalmente para la documentación API, aunque no es óptimo de estilo de codificación.
Pasemos a utilizar apidoc para generar la documentación.
Generando la Documentación
Puede revisar apidoc comandos ejecutando sin argumentos:
1 |
$ ./vendor/bin/apidoc |
2 |
|
3 |
This is Yii version 2.0.10. |
4 |
|
5 |
The following commands are available: |
6 |
|
7 |
- api Generate class API documentation. |
8 |
api/index (default) Renders API documentation files |
9 |
|
10 |
- guide This command can render documentation stored as |
11 |
markdown files such as the yii guide |
12 |
guide/index (default) Renders API documentation files |
13 |
|
14 |
- help Provides help information about console commands. |
15 |
help/index (default) Displays available commands or the detailed |
16 |
information |
17 |
|
18 |
|
19 |
To see the help of each command, enter: |
20 |
|
21 |
apidoc help <command-name> |
Usaré la opción de api, y aquí están las configuraciones que usted puede hacer:
1 |
$ ./vendor/bin/apidoc help api |
2 |
|
3 |
DESCRIPTION |
4 |
|
5 |
Renders API documentation files |
6 |
|
7 |
|
8 |
USAGE |
9 |
|
10 |
apidoc api <sourceDirs> <targetDir> [...options...] |
11 |
|
12 |
- sourceDirs (required): array |
13 |
$sourceDirs |
14 |
|
15 |
- targetDir (required): string |
16 |
$targetDir |
17 |
|
18 |
|
19 |
OPTIONS |
20 |
|
21 |
--appconfig: string |
22 |
custom application configuration file path. |
23 |
If not set, default application configuration is used. |
24 |
|
25 |
--color: boolean, 0 or 1 |
26 |
whether to enable ANSI color in the output. |
27 |
If not set, ANSI color will only be enabled for terminals that support it. |
28 |
|
29 |
--exclude: string|array |
30 |
files to exclude. |
31 |
|
32 |
--guide: string |
33 |
url to where the guide files are located |
34 |
|
35 |
--guidePrefix: string (defaults to 'guide-') |
36 |
prefix to prepend to all guide file names. |
37 |
|
38 |
--help, -h: boolean, 0 or 1 |
39 |
whether to display help information about current command. |
40 |
|
41 |
--interactive: boolean, 0 or 1 (defaults to 1) |
42 |
whether to run the command interactively. |
43 |
|
44 |
--pageTitle: string |
45 |
page title |
46 |
|
47 |
--template: string (defaults to 'bootstrap') |
48 |
template to use for rendering |
Para generar mi documentación de la API, cuyo directorio también es api, voy a hacer lo siguiente:
1 |
$ ./vendor/bin/apidoc api api api/web/docs |
2 |
--pageTitle=MeetingPlanner |
3 |
TargetDirectory already exists. Overwrite? (yes|no) [yes]:yes |
4 |
Searching files to process... done. |
5 |
Loading apidoc data from cache... done. |
6 |
Checking for updated files... done. |
7 |
8 files to update. |
8 |
Processing files... done. |
9 |
Updating cross references and backlinks... done. |
10 |
Rendering files: done. |
11 |
generating extension index files...done. |
12 |
generating search index...done. |
13 |
35 errors have been logged to api/web/docs/errors.txt |
14 |
214 warnings have been logged to api/web/docs/warnings.txt |
Porque no he terminado de comentar todo el árbol, hay errores y advertencias generadas. Más a menudo se ven algo como esto:
1 |
Array |
2 |
( |
3 |
[0] => Array |
4 |
( |
5 |
[line] => 31 |
6 |
[file] => api/controllers/ParticipantController.php |
7 |
[message] => Method behaviors has no parent to inherit from in api\controllers\ParticipantController. |
8 |
) |
9 |
|
10 |
[1] => Array |
11 |
( |
12 |
[line] => 32 |
13 |
[file] => api/controllers/PlaceController.php |
14 |
[message] => Method behaviors has no parent to inherit from in api\controllers\PlaceController. |
15 |
) |
Navegar por la Documentación
Publicación de la documentación en la línea de comandos de apidoc anterior a /api/web/docs significa que puede ver la documentación de Meeting Planner de la web.
Por ejemplo, aquí está el UserTokenController:
Este es el método de actionRegister() que muestra los comentarios de parámetro reflejados con el in header en información.
Aquí está la Documentación de MeetingController:
Y este es el método de actionMeetingplacechoices():
Como se puede ver, esto es extremadamente útil para compartir una API con programadores de terceros en tiempo real como entrega el código. El gran beneficio es que elimina la necesidad de mantener manualmente la documentación de la API por separado.
En cualquier momento puede eliminar una tarea de una startup, es una gran victoria.
De Cara al Futuro
Espero que usted ha visto un poco del poder de la extensión de apidoc de Yii2. Se puede utilizar para mantener documentación para todo el código, y también le anima a seguir con los comentarios, que voy a hacer más de momento.
Si usted tiene cualquier pregunta o comentario, por favor publicarlos en los comentarios. Si desea mantenerse al día sobre mi futuro Envato Tuts + tutoriales y otras series, por favor visite mi página de instructor o sigame @reifman. Definitivamente comprobar hacia fuera mi serie mi startup y Meeting Planner.
Enlaces Relacionados
