Advertisement
  1. Code
  2. Automation

Programación con Yii: Generar la Documentación

by
Read Time:6 minsLanguages:
This post is part of a series called How to Program With Yii2.
Programming With Yii2: Building Community With Voting, Comments, and Sharing
This post is part of a series called Building Your Startup With PHP.
How to Build a User Tour With Shepherd in JavaScript

Spanish (Español) translation by Alfonso Mora (you can also view the original English article)

Final product imageFinal product imageFinal product image
What You'll Be Creating

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

Programming With Yii - APIdoc installation GuideProgramming With Yii - APIdoc installation GuideProgramming With Yii - APIdoc installation Guide

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:

Programming With Yii - Auto-Generated Framework DocumentationProgramming With Yii - Auto-Generated Framework DocumentationProgramming With Yii - Auto-Generated Framework Documentation

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:

Programming With Yii Generating Documentation - Guide generated from MarkdownProgramming With Yii Generating Documentation - Guide generated from MarkdownProgramming With Yii Generating Documentation - Guide generated from Markdown

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:

Y coloque un bloque de comentario sobre cada controlador o la determinación del modelo:

Luego, coloque un bloque de comentario detallado sobre cada método, que incluye parámetros, valores devueltos y excepciones:

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."

Como valores por defecto se incluyen en las definiciones de función, no hay ningún daño real hecho:

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:

Usaré la opción de api, y aquí están las configuraciones que usted puede hacer:

Para generar mi documentación de la API, cuyo directorio también es api, voy a hacer lo siguiente:

Porque no he terminado de comentar todo el árbol, hay errores y advertencias generadas. Más a menudo se ven algo como esto:

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:

Programming With Yii Generating Documentation - UserTokenController ExampleProgramming With Yii Generating Documentation - UserTokenController ExampleProgramming With Yii Generating Documentation - UserTokenController Example

Este es el método de actionRegister() que muestra los comentarios de parámetro reflejados con el in header en información.

Programming With Yii Generating Documentation - UserTokenController Example actionRegister methodProgramming With Yii Generating Documentation - UserTokenController Example actionRegister methodProgramming With Yii Generating Documentation - UserTokenController Example actionRegister method

Aquí está la Documentación de MeetingController:

Programming With Yii Generating Documentation - MeetingController ExampleProgramming With Yii Generating Documentation - MeetingController ExampleProgramming With Yii Generating Documentation - MeetingController Example

Y este es el método de actionMeetingplacechoices():

Programming With Yii Generating Documentation - MeetingController Example actionMeetingplaces exampleProgramming With Yii Generating Documentation - MeetingController Example actionMeetingplaces exampleProgramming With Yii Generating Documentation - MeetingController Example actionMeetingplaces example

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

Advertisement
Advertisement
Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.