Migration of working documentation to OpenAPI for HeadHunter
SimbirSoft specialists were involved in a significant project for HeadHunter that spanned approximately three years. The objective was to migrate the working documentation of an internal corporate software product from Markdown format to the modern interactive OpenAPI tool. Additionally, the team was responsible for enhancing autotests with new functionality and optimizing the legacy code.
The introduction of new functions and transition capabilities enabled the company to create a cohesive user environment tailored for various work purposes. For HeadHunter developers, this meant having interactive instructions readily available for efficient data uploads, whether for service integration or automation tasks. OpenAPI also facilitates the identification of backward compatibility issues, synchronizes Russian and English documents, and allows for the configuration of different validation types for incoming and outgoing objects.
Task
The goal was to migrate the working documentation of an internal corporate software product from Markdown format to the modern interactive OpenAPI tool, enhance autotests with new functionalities, and optimize legacy code.
Previous Process:
Prior to the implementation of interactive instructions, useful information was provided in plain text format, which was inadequate for process automation.
Solution
The new OpenAPI tool is significantly more functional than Markdown, as it organizes documentation and provides numerous options for interaction. OpenAPI enables data relevance checks, fact verification, and the generation of Data Transfer Objects (DTO) for autotests. This has led to reduced development time for integrators and simplified documentation validation.
Example of Automation with OpenAPI:
Using internal data, the system can automatically generate classes for tests and validate responses to queries. This transforms everything into a clear structure with clickable elements and a threaded hierarchy.
Result
In the project, SimbirSoft specialists monitored, checked and corrected the working documentation, generated new classes based on it, replaced self-written classes with auto-generated ones, adapted old methods for using new classes, ensured that autotests were validated, and made a code review.
As a whole, thanks to the transition, we managed to achieve:
DTO generation according to documentation;
the ability to check documentation for validity compliance; standardization of documentation writing and the resulting benefits.
Headhunter has successfully completed an autotest project, which includes global refactoring and the migration of documentation to OpenAPI. The public portion of the project can be accessed via the provided link.
Why Do Developers Need Instructions?
To Work with the Application Without Logging into the Website:
Profile specialists frequently utilize the API to search for and update information without manual intervention. This eliminates the need to visit a specific website to obtain answers, making the process more efficient for users who prefer streamlined access to data.
For Rapid Data Upload and Process Automation:
API instructions provide quick access to data, allowing developers to filter and retrieve information efficiently. They can easily upload data in text format, apply filters, and obtain results for specific queries. This method is particularly advantageous for experts developing internal systems and integrating new services and products through APIs.
To Enhance Product Quality:
The verification of the working system relies on the specifications outlined in the documentation. The system checks the data against these instructions, and when everything functions correctly, autotests will not report any errors, ensuring that the application operates as intended.