I've been searching for the past couple of days for some way to document the API for a microservices architecture I'm working on. First, I'll give a very quick description of the project:
The short of it is that I'd like to know how other people document the models that are published to their message bus. I've seen quite a few projects (like Swagger) that help document REST calls, but we're not using REST. Our application is almost entirely event-based with pub-sub messaging using JSON.
My first thought was to document the JSON with JSON-Schema and use a tool to convert that to nicely-formatted API docs. That would probably work okay, but what bothers me is that there don't seem to be any tools to automate the schema generation as part of a build process. If our models diverge from the API documentation, I want it to be a build error. Even better, if there was some way to auto-generate the basic documentation as part of the build process, the docs could be kept in sync.
How do you guys do it? The lack of documentation tools specific to a message bus architecture in favor of REST is making me question our decision to use a messaging architecture based on message queues. :)
...there don't seem to be any tools to automate the schema generation...
Agreed that tooling is thin on the ground. However, there is this: https://github.com/NJsonSchema/NJsonSchema
How do you guys do it?
Interestingly I was having this exact discussion with a colleague not 10 minutes ago :p
We require a build (or acceptance test) failure if a model deviates from a pre-defined schema.
So you could have a step in your build which uses the NJsonSchema package to generate the schema from your model. Then you have a comparison step which compares the outputted schema against the API docs schema.
Conversely, you could generate code from your schema and then compare the output to the models in your build output.
...question our decision to use a messaging architecture based on message queues..
Stay the course, friend.