Fosrestbundle: Generación de documentación API REST a partir de rutas

Consulte el screencast de http://getfrapi.com/ para inspirarse.

Ya lo he visto. Pero no me gustan muchas cosas en su realización. En primer lugar, su REST no es RESTful :-D

"inspiración" y no estaba hablando de su descanso sino de su generación de documentos (y pruebas) :)

A mí personalmente no me gusta, pero ¿podríamos hablar de la generación de la documentación en formato WADL?

http://www.w3.org/Submission/wadl/

Me pregunto si una dirección mejor que la generación sería proporcionar algunos ayudantes de visualización que permitieran la creación rápida de controladores/vistas de documentación. Esto parece mejor que simplemente generar una estructura y sería más extensible/mantenible. En otras palabras, creo que generar documentos API funciona muy bien para el caso de uso de FRAPI (colocar en una aplicación), pero me pregunto si necesitamos esta función "tal cual" o si tiene sentido.

¿Estamos hablando de documentación para los clientes?

Tenga en cuenta que eso es lo que REST intenta evitar :)

odino: claro. pero hay cosas como el hecho de que incluso si sigues HATEAOS necesitas inspeccionar los encabezados. Además, si bien debe saber esperar diferentes códigos de estado, sigue siendo bueno saber qué códigos de estado son "más probables". es agradable para una revisión informal de la API.

también otro tema que debe ser ignorado: a algunos clientes les gusta matar árboles y es bueno no tener que perder mucho tiempo llenando estas páginas de papel :)

de acuerdo, lo único que debemos evitar es depender en gran medida de la documentación generada, de lo contrario replicaríamos WSDL

pulgares hacia abajo para los asesinos de árboles :)

Hasta donde yo sé, los verdaderos documentos de la API REST tratan sobre la definición de tipos de medios y sus relaciones, no de URL. Por ejemplo, http://kenai.com/projects/suncloudapis/pages/Home , http://amundsen.com/media-types/collection/

Pero para las API HTTP simples, que será el caso del 80 % de los proyectos web, esta función seguirá siendo útil.

Sí vladar, las plantillas URI son obviamente malas. Pero si necesitamos desarrollar un paquete REST, debemos seguir esos principios.

Una plantilla de URI encajaría bien para un ApiBundle

Podría tomar conceptos de http://swagger.wordnik.com/

:+1: a Swagger. ¡Esto se ve increíble!

Para crear una experiencia similar, podríamos:

• Métodos de análisis marcados como @apidoc o algo así
• Obtenga una descripción del método y los parámetros de docblock en los métodos marcados con @apidoc
• Permita la prueba en línea de las llamadas por acción.

Considerándolo todo, creo que lograr pantallas como Swagger es bastante factible y tiene mucho sentido para este paquete.

Otra opción sería simplemente generar el JSON que consume Swagger pero que tiene algo de peso (Java)... Preferiría ver una implementación "me gusta".

Generar JSON compatible fue mi primer pensamiento. Profundizaré un poco más el fin de semana, tal vez haya algunos prototipos rápidos y sucios posibles.

@pminnieur parece que podríamos proporcionar fácilmente la misma funcionalidad básica en lugar de integrar.

Al menos podría funcionar como https://github.com/FriendsOfSymfony/FOSJsRoutingBundle , simplemente agregando algunos HTML/CSS sofisticados y exponiendo sus rutas RESTful con algún tipo de documentación API. Tal vez podríamos usar algunas anotaciones para respaldar más información.

Me gustaría comenzar con esto, pero creo que sería mejor poner el código en un paquete dedicado (por ejemplo, FOSRestAPIExplorerBundle). La pregunta es, ¿soportaremos solo la API de Swagger (de modo que Swagger se use para visualizar la información recopilada y expuesta en JSON) o también proporcionaremos nuestra propia interfaz web?

un paquete separado suena como una buena idea. si solo admitimos swagger, es posible que queramos decirlo en el nombre del paquete. No sé si también queremos apoyar algo más. depende de su motivación y la calidad de la arrogancia. una pregunta sobre swagger: ¿cómo funciona eso con las API internas que uno no quiere exponer a un servicio externo?

Creo que simplemente no debe hacer que la URL que devuelve el Swagger JSON sea pública si no quiere que sea pública ...: D En serio, me gustaría usar anotaciones y si no quiere que una ruta sea público, no agregará la anotación @Expose() ni agregará @Expose(false) , algo como esto. Al igual que FOSJsRoutingBundle, se puede configurar cómo manejarlo (exponer todo de forma predeterminada o exponer la lista blanca). Si quiere decir "aquí hay un enlace para nuestra API pública y este enlace es solo para usted", podemos agregar una anotación como @Api("public") y @Api("private") incluido el componente de seguridad para que pueda entregar una API diferente documentaciones a diferentes personas (y controlar el acceso a ellas).

Para el nombre: me gustaría tener un nombre genérico, Swagger sería el primer servicio de documentación de API que se admitiría. Si las personas desean agregar cualquier otro servicio, pueden hacerlo (y no deben comenzar desde cero). @odino, por ejemplo, podría agregar el soporte WADL. Al menos también me gustaría proporcionar una interfaz web.

Creé un repositorio de GitHub hasta ahora para recopilar ideas y problemas antes de comenzar. Siéntase libre de abrir problemas para cualquier pregunta o tema para discutir (los nombres también podrían discutirse, seguro) ;-)

https://github.com/pminnieur/FOSRestApiExplorerBundle

está bien. una vez que las cosas se han puesto en forma... podemos moverlo a FOS

¿Está planeando aprovechar https://github.com/wordnik/swagger-ui como "display"?

en primer lugar, si. solo genere json conforme a swagger-spec para ser utilizado por swagger-ui.

cierre a favor de https://github.com/nelmio/NelmioApiDocBundle

Sé que esto es muy antiguo, pero algunas cosas cambiaron desde entonces y encontré esto relativamente rápido mientras buscaba un paquete/paquete para Swagger/Openapi.
¿Alguna posibilidad de reconsiderar esto? Dado que NelmioApiDocBundle está abandonado y no veo ninguna alternativa real que se integre en Symfony para Swagger / OpenApi (¿o cualquier otro realmente, RAML, ...?).