Xsolla is an international company that works with many developers and publishers from the United States, Russia South Korea, and the countries of CIS. In order to provide the latest information for rapid integration of customers, the Xsolla team came up with an innovative tool to automatically generate API documentation.
Support Actual Documentation
Typically, during the development of the documentation process, updating the actual API documentation is left for last. Maintaining the current documentation for API requires a separate step in the development process and sometimes needs a documentation specialist to handle the updates. It also helps if the specialist has programming skills in order to better describe the API functionality.
In the process of project development, there are many situations where API methods change for instance, improving functionality, fixing bugs, and adding new features. Keeping the API documentation up-to-date proves to be a tenacious task as a specialist must constantly monitor and add updates into the documentation as they are released.
There is a big risk that some changes might not go into the documentation even if we have a separate specialist focused solely on keeping the documentation up-to-date.
Fully-Automated API Documentation
At Xsolla, it is necessary for us to have a constantly updated API documentation. We’ve created an external API for our clients which is used by thousands of our partners globally. Because of our global presence, we cannot make any of our clients wait for our newly added features in our documentation to be manually updated. The API documentation is one of the most important elements of Xsolla because by having a clear, well-thought out form, game developers gain a sense of the timeframe of integration and amount of resources necessary.
Our specialists have come up with a method to revel in the best of both worlds by automatically generating the API through the comments in the code filled by the developers and by maintaining a clear description of the complex API in a time-efficient manner.
Annotations in Symfony
Annotations in Symfony are multi-line comments in which you can describe methods, variables, routings, input parameters, etc.
If the method significantly changes the behavior, it is reflected in the description of its input and output parameters in the annotation.
We use the Symfony forms to input parameter validation. Description of parameters and their types are also listed in the code.
Through this approach, the team ensures that any changes in the code will also be reflected in the description of the method and input parameters.
Getting a Response From API
Another feature Xsolla approach is that for each method on the basis of the URL and data input system automatically performs the test method with the input data and detects response from the API, which fall into the documentation. Thus, when generating documentation, we again check the format of the input data. This again ensures that records 100% of the code.
Another feature that we implement in Xsolla is: we execute each method based on it’s URL and input parameters with test data. Once these methods are executed we put the responses right into the documentation itself. This allows us to double-check the format of the input data and also allows us to guarantee that the documentation matches the code.
Creating Documentation in Markdown
In order to generate documentation for your API’s, we use NelmioApiDocBundle .
We selected Markdown to write our documentation. This tool is perfect for viewing the document changes made by the developers.
In the beginning, a technical specialist needs to write all of the static parts of the documentation manually including the Introduction and Explanation of Methods. This process cannot be automated by computers yet unfortunately.
Everything that needs to be in documentation has to be written in Markdown including: URL, description of methods, input parameters, and samples in several technologies (For now: HTTP and cURL).
Markdown allows you to easily monitor changes and add sections with static content conveniently.
Creating Documentation in HTML
At first, we generated documentation using slate but as time went on we created our own solution.
We are converting Markdown data to HTML subsystems written in node.js and managed by gulp.
Using various libraries including animate.css, Bourbon, lodash, normalize-CSS, retina.js, and underscore, we transform Markdown into HTML.
Now you only have to collect the final HTML files and upload them to your web server. For this, as for all other code deployments, we wrote a recipe for Capistrano . Simply type in a couple of console commands and users get to enjoy the latest version of documentation API in conjunction with the release of the modified code.
The results can be seen on developers.xsolla.com .
After a few weeks of development, we have a system that allows us to keep our documentation up-to-date. Our solution allows you to maintain a list of changes and supports new feature implementation. This solution also allows us to maintain a list of changes after every new release. Now we can share this information conveniently with our partners.
Automating updates doesn’t replace the technical specialists duties but it definitely helps facilitate work efficiency and provides customers with a fast and reliable reference resource.