rest - ejemplo - que es apiary
Buena herramienta de generación de código de reposo y documentación (4)
He estado considerando una herramienta de documentación para construir un back-end para un servicio web que se utilizará en múltiples clientes junto con OAuth y la posibilidad de múltiples revisiones. Ya sabía sobre colmenas, pero investigando un poco encontré otras soluciones bastante buenas con promesas lucrativas.
RAML parece ser una prometedora generación de código y una reutilización api. Pero no parece ser capaz de crear un servidor simulado. Y no puedo entender por qué apiblueprint no se puede usar para generar libs del lado del cliente y esqueletos del lado del servidor para API REST.
El mejor caso de uso para nosotros estará en la documentación de la API, la biblioteca cliente iOS / Android / wp / js para consumir el servicio se puede generar automáticamente junto con una aplicación node express / restify que proporciona esqueleto para escribir código. Junto con pruebas de API y pruebas de carga.
¿Qué solución de RAML / Swagger / Apiary es la mejor para esto?
Descargo de responsabilidad: trabajo para Apiary
No creo que sea una buena idea.
Su necesidad de simulacro de servidor hace alusión al hecho de que ha aceptado la ruta de la descripción antes de la implementación, lo cual es bueno.
Sin embargo, la idea es que una vez que se desarrolle contra un servidor simulado, itere sobre el diseño de la API (esa es una de las razones por las que tiene sentido hacerlo en herramientas de "texto" en lugar de código) ... y esa es la parte difícil .
Existen algunas herramientas emergentes que admiten el andamiaje, pero el verdadero problema es cómo actualizar la aplicación con scaffolded después de que se haya actualizado el plan. Sé que algunas personas están abordando esto, pero aún no se han publicado.
En mi opinión, el mejor enfoque es desarrollar prototipos reales contra la API burlada para probar el UX de la aplicación resultante. Una vez que el diseño es razonablemente estable, usted comienza a desarrollar otros clientes además de servidores, con el tiempo extendiendo el diseño original.
Los prueba con las herramientas respectivas encontradas en los respectivos idiomas, ya que son los mejores para el caso de uso dado. Para probar que la implementación se ajusta a blueprint (también conocido como contrato escrito), puede usar dredd .
Cualquier herramienta que coopere además de eso debería tomar el plano como una entrada en lugar de generar la biblioteca para extenderla manualmente lo cual es imposible de mantener.
RAML proporciona un servicio de burla alojado integrado y gratuito que puede implementar con un solo clic en el Diseñador de API . Una vez que haya habilitado la burla, intente: se habilitará de inmediato en la consola de la API integrada, y podrá ejercer aún más su API simulada utilizando el URL base insertado en su archivo RAML.
Además, seremos proveedores abiertos de frameworks de servidores adicionales (ya contamos con frameworks Mule y JAX-RS) en el futuro cercano (incluido Node). La generación de clientes está un poco más lejos, pero también está llegando muy pronto (javascript primero, luego otros).
Divulgación: estoy muy involucrado con la iniciativa RAML, y trabajo para MuleSoft como Gerente de Producto para muchas de las herramientas RAML que desarrollamos.
Si la consola RAML no es lo suficientemente liviana, es posible que https://github.com/kevinrenskers/raml2html sea realmente útil y fácil de usar.
No contiene todas las funciones que tiene la consola RAML (como Try out, para probar la API desde allí), pero sigue siendo una excelente herramienta de documentación.
Consulte Swagger Codegen (gratis, de código abierto), que puede generar tanto stubs de servidor como API en diferentes idiomas.
Muchas empresas / proyectos lo están utilizando en producción: https://github.com/swagger-api/swagger-codegen#companiesprojects-using-swagger-codegen
Lenguajes / frameworks soportados:
Clientes API : ActionScript, Bash, C # (.net 2.0, 4.0 o posterior), C ++ (cpprest, Qt5, Tizen), Clojure, Dart, Elixir, Go, Groovy, Haskell, Java (Jersey1.x, Jersey2.x, OkHttp , Retrofit1.x, Retrofit2.x, Feign), Node.js (ES5, ES6, AngularJS con anotaciones del compilador de cierres de Google) Objective-C, Perl, PHP, Python, Ruby, Scala, Swift (2.x, 3.x ), Typescript (Angular1.x, Angular2.x, Fetch, jQuery, Node)
Trozos de servidor : C # (ASP.NET Core, NancyFx), Erlang, Go, Haskell, Java (MSF4J, Spring, Undertow, JAX-RS: CDI, CXF, Inflector, RestEasy), PHP (Lumen, Slim, Silex, Zend Expressive) ), Python (Frasco), NodeJS, Ruby (Sinatra, Rails5), Scala (Finch, Scalatra)
Generadores de documentación API : HTML, Confluence Wiki
Descargo de responsabilidad: soy un colaborador principal del proyecto de código abierto.