4

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:

  • Written in C#, .NET 4.6.1
  • Using NetMQ with x-pub/x-sub proxy as a "message broker"
  • All communication is plain C# objects serialized to JSON
  • Some clients are JavaScript in the browser, others are .NET applications

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. :)

user1094821
  • 1,495
  • 1
  • 11
  • 10

1 Answers1

1

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

tom redfern
  • 30,562
  • 14
  • 91
  • 126
  • Thank you for the link to NJsonSchema! This will be super helpful. I started working on a code parser based on Roslyn that can parse the comments out of our model code and build documentation automatically. I used this page as a guide: https://github.com/dotnet/roslyn/wiki/Getting-Started-C%23-Syntax-Analysis I am planning to generate Markdown that gets run through mkdocs in readthedocs format. With schema validation in the build process and automatic documentation generation, I think this solution might work. I'm surprised there's not more tooling around this sort of thing! – user1094821 Jun 30 '16 at 17:59
  • @user1094821 - glad you found it useful. let me know your final solution... – tom redfern Jul 01 '16 at 09:44