Hello there, is there any way to properly document RPC calls, dependencies,
published events and events service is subscribed to? Something like
swagger for REST APIs? We are developing multiple services and are
interested in whether it is possible to do, may be some kind of a Sphinx
plugin?
Hi,
There's nothing out of the box, but there are a lot of options and
possibilities. Part of the reason it's not "built-in" is that there are so
many possibilities, but the foundations are there to make something quite
cool.
Nameko tries to have everything introspectable from the service class --
given a service class you can iterate over the methods to find Entrypoints
and the attributes to find DependencyProviders. You could easily pull the
docstrings out of the methods, and group them by entrypoint type (e.g. RPC
methods, event handlers). DependencyProviders may also have docstrings or
further-introspectable attributes.
Determining published events requires adding some declarations on your
service class. If a service method just calls ``self.dispatch("event_type",
"payload')`` you'd have to parse the code to figure out that it's
dispatching an event; but if you made it
``self.dispatch(self.events["event_type"], "payload')`` you could at least
inspect ``<service_cls>.events`` to figure out what types of events a given
service dispatches.
All of this could be done with a Sphinx plugin I think.
Going further, you could use the standalone RPC proxy and event dispatcher
to create something that allows you to actually make calls to a running
service from inside the docs.
Finally, for HTTP entrypoints, there's the possibility of actually using
Swagger. The blog post at
http://brunorocha.org/python/microservices-with-python-rabbitmq-and-nameko.html
uses flasgger <https://github.com/rochacbruno/flasgger>, which renders
Swagger docs for a Flask app. Nameko's HTTP entrypoint is so similar to
Flask's (since it's built on Werkzeug) that it would be pretty easy to fork
or re-implement flasgger to do the same thing for Nameko services.
Hope that helps,
Matt.
···
On Tuesday, February 7, 2017 at 10:00:20 AM UTC, trikst...@gmail.com wrote:
Hello there, is there any way to properly document RPC calls,
dependencies, published events and events service is subscribed to?
Something like swagger for REST APIs? We are developing multiple services
and are interested in whether it is possible to do, may be some kind of a
Sphinx plugin?
Thank you a lot for your reply, I will investigate everything you've
suggested.
···
вторник, 7 февраля 2017 г., 15:54:00 UTC+3 пользователь Matt Yule-Bennett написал:
Hi,
There's nothing out of the box, but there are a lot of options and
possibilities. Part of the reason it's not "built-in" is that there are so
many possibilities, but the foundations are there to make something quite
cool.Nameko tries to have everything introspectable from the service class --
given a service class you can iterate over the methods to find Entrypoints
and the attributes to find DependencyProviders. You could easily pull the
docstrings out of the methods, and group them by entrypoint type (e.g. RPC
methods, event handlers). DependencyProviders may also have docstrings or
further-introspectable attributes.Determining published events requires adding some declarations on your
service class. If a service method just calls ``self.dispatch("event_type",
"payload')`` you'd have to parse the code to figure out that it's
dispatching an event; but if you made it
``self.dispatch(self.events["event_type"], "payload')`` you could at least
inspect ``<service_cls>.events`` to figure out what types of events a given
service dispatches.All of this could be done with a Sphinx plugin I think.
Going further, you could use the standalone RPC proxy and event dispatcher
to create something that allows you to actually make calls to a running
service from inside the docs.Finally, for HTTP entrypoints, there's the possibility of actually using
Swagger. The blog post at
http://brunorocha.org/python/microservices-with-python-rabbitmq-and-nameko.html
uses flasgger <https://github.com/rochacbruno/flasgger>, which renders
Swagger docs for a Flask app. Nameko's HTTP entrypoint is so similar to
Flask's (since it's built on Werkzeug) that it would be pretty easy to fork
or re-implement flasgger to do the same thing for Nameko services.Hope that helps,
Matt.On Tuesday, February 7, 2017 at 10:00:20 AM UTC, trikst...@gmail.com > wrote:
Hello there, is there any way to properly document RPC calls,
dependencies, published events and events service is subscribed to?
Something like swagger for REST APIs? We are developing multiple services
and are interested in whether it is possible to do, may be some kind of a
Sphinx plugin?