Documentation of # microservices



    The original article is a reflection on why documentation in the world of microservices is critically necessary and how it can be created and published using swagger. It’s definitely not a step-by-step setup guide.



    Introduction


    A few months ago, one of our backend intern developers got a task - to develop 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 more detailed information about some specific users in the report. I decided to update this service myself. “Just get the data from our user service and paste it into the email,” I thought then.

    It took me several hours to do this, and I even had to connect two other developers just to find the right REST endpoints and the necessary menus. "Never again. There must be a more correct method to do this ... ”, - it was spinning in my head all this time.

    Microservice architecture implies a set of independent services that communicate with each other, and for the end user it 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. Usually, 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 it a little later, but for now let's discuss the basics - the documentation format.


    Swagger



    Documentation should be easy to read, write, parse, generate, correct, update, and more. The solution should be so simple that even the most lazy 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 power lies in additional tools . Swagger has a huge amount of free utilities (both official and community-written) that can make life (yours and your colleagues) a little happier. You can install all this on your own servers and see how it works - for example, try working with a document browser or Swagger online editor.


    How do we do this?


    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 has a file with a Swagger description in a specific folder and it is all stored directly in the git repository. Descriptions can be either generated using the 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 assembly of the project we can automatically check the compliance of REST endpoints and documentation. Inconsistencies will generate warnings, and thereby encourage the developer to keep the documentation up to date.


    Storing documentation inside a microservice allows us to display it at any time directly from this microservice during operation. 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 special 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, makes some minimal modifications (deduplication, removal of unnecessary attributes) and generates a single Swagger file containing complete up-to-date information for the entire project.


    Publishing documentation.


    Centralized storage and editing of documentation is only the first step. The next is to make it accessible 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, the Swagger UI generates HTML elements for all of your REST endpoints, which you can further organize with HTML markup.




    By default, Swagger UI loads its own Swagger file with examples. 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 at Ataccama started using Docker, and so we thought, why not pack all the documentation in a separate docker container , upload it to our private repository, and then deploy the cluster to the docker? Jenkins can do this in just a few seconds. As a result, we always have updated documentation available for viewing through a browser.


    In addition, using docker gives us several more advantages:


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


    • Each docker image has a version, and if you need documentation for an older release, just upload another 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 using 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 praising Swagger, we still haven't found a convenient way to document asynchronous messages. In fact, in Atakkam we are unhappy with our current decision and are still trying to find something simpler and more beautiful to describe message queues and their structures. If you have ideas on how to do this 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 that 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.


    Also popular now: