Documenting # microservices

The original article is a reflection on why documentation in the world of microservices is critical and how it can be created and published using swagger. Step-by-step instructions on how to configure it is not exactly.

Introduction

A few months ago, one of our backend interns developers received the task of developing a new simple service. The service was supposed to generate email reports on user activity. There was nothing complicated in the task and the intern succeeded. However, after a few weeks, we wanted to include in the report more detailed information about some specific users. I decided to upgrade this service myself. “Just get the data from our user service and paste it into the email,” I thought then.

It took me a few hours, and even had to connect two other developers just to find the right REST endpoints and the necessary structure changes. "Never again. There should be a more correct method to do it ... ”, - it has been spinning in my head all this time.

Microservice architecture involves a set of independent services that communicate with each other, and for the end user looks like a single program. One of the most popular protocols for messaging between microservices is REST. The problem is that REST is not a descriptive protocol itself. This means that the client must know the specific combination of URL, HTTP method and response format. In some cases, you also need to know the format of the request body. Typically, the implementation of the REST interface is based on the general principles and traditions adopted in your organization. In any case, REST endpoints should always be described in one specific document, accessible to all other developers . We will talk about how and where to store a bit later, but for now let's discuss the basics - the format of the documentation.

Swagger

Documentation should be easy to read, write, parse, generate, correct, update, and more. The solution should be so simple that even the laziest developers use it. After a little research, we at Ataccama decided to use Swagger to document our REST APIs.

Swagger is a framework and specification for defining REST APIs in a user-friendly and computer-friendly format (in our case JSON or YAML). But Swagger is not just a specification. Its main strength lies in additional tools . For Swagger, there are a huge number of free utilities (both official and written by the community) that can make life (yours and your colleagues) a little happier. You can install it all on your own servers and see how it works - for example, try working with the document browser or Swagger online editor.

How do we do it?

If you also think that Swagger is great, then read on. Now there will be some details about how we use it in Ataccama, in the mysterious world of microservices.

Each microservice in a certain folder contains a file with a Swagger description and it is all stored directly in the git-repository. Descriptions can be either generated using a Swagger generator or written there manually. The beauty is that JSON and YAML formats are used to write definitions. They are easy to parse, and during the project build we can automatically check the compliance of REST endpoints and documentation. Inconsistencies will generate alerts, and thus encourage the developer to keep the documentation up to date.

Keeping documentation inside the microservice allows us to display it at any time directly from this microservice in the process. This helps to test and debug REST endpoints in the process of deploying the service on your own machine. Swagger also has a web-based tool for testing REST endpoints.

Since each microservice provides its own documentation, we can set up a specific task for Jenkins (or any other CI server) that will generate complete documentation for the entire project. This task collects Swagger files from all microservices, produces some minimal modifications (deduplication, removal of unnecessary attributes) and, at the output, generates a single Swagger file containing the complete up-to-date information for the entire project.

The publication of the documentation.

Centralized storage and editing of documentation is only the first step. The next is to make it available to all developers , testers and other interested people in the company. And Swagger UI is exactly what you need for this. Using a small JavaScript library, Swagger UI generates HTML elements for all your REST endpoints, which you can then organize using HTML markup.

By default, Swagger UI loads its own Swagger example file. All other APIs must be loaded manually. But the configuration takes only a few seconds.

var swaggerUi = new SwaggerUi({ url: 'http://example.com/swagger.json', dom_id: 'swagger-ui-container' }); swaggerUi.load(); 

Now we have the generated documentation in a readable form. Time to send it to the server.
Some time ago we started using Docker at Ataccama, so we thought, why not pack all the documentation into a separate docker container , load it into our private repository, and then put it into the docker cluster? Jenkins can do it in just a few seconds. As a result, we always have updated documentation available for viewing through the browser.

In addition, using the docker gives us a few more advantages:

• Each developer can simply download the documentation and run it on his own computer with just one team.

  
  
• Each docker image has a version, and if you need documentation for an older release, simply download a different image with a different docker tag.

And this is just the beginning.

This is just a general idea of ​​how we generate documentation for REST endpoints and publish it with a docker for our microservices. Unfortunately, synchronous REST is not all that we need to document in this labyrinth of microservices. At some point, I want to switch to more advanced communication systems, asynchronous messaging, queues, event subscriptions, and more.

Despite the praise of Swagger, we still haven't found a convenient method of documenting asynchronous messages. In fact, in Atakkame, we are unhappy with our current solution and are still trying to find something simpler and more beautiful to describe message queues and their structures. If you have an idea how to do it better, write in the comments. Any interesting ideas are welcome.

The original article is here .

By Lubos Palisek
Backend software developer in Ataccama. Greedy for new cloud based technologies and ideas.
')
Ataccama Corporation is an international software company specializing in data quality management, master data management and enterprise data management solutions, whose solutions have already been used by more than 250 companies, ranging from medium-sized enterprises to international companies from various industries.

I will gladly translate all your questions and recommendations to the author.