Automation of API documentation

Automation of API documentation is project where we wanted to automate process of API documentation generation.

Table of Contents

• Motivation for the automation of API documentation
• Concept of API documentation generator
• Implementation of API documentation generator
• Results and benefits

Motivation for the automation of API documentation

Before this project we used Swagger standard to manually write and generate documentation for our API. This was resulting in several things that were not optimal:

• hours of coding invested in something might be generated (partially or fully)
• manual mistakes (i.e. forgotten required field or any other forgotten flag)
• complex change management (i.e. each change on API should be manually found within 50.000+ lines of API documentation document and modified)

Concept of API documentation generator

Firstly, we decided to monitor manual process, find out which knowledge sources developers are using to generate a documentation.

Secondly, we tried to optimize parts of the process and semi-generate some parts of documentation (i.e. properties) to avoid manual errors and speed up process.

Finally, at the end we created a mechanism which is actually reading code base, recognizes attributes within controllers and levels of accessibility within our API. Then mechanism combines these values with database and attributes descriptions. At the end, it generates complete documentation out of the gathered data.

Implementation of API documentation generator

The Swagger generator is a code-generator component which generates OpenAPI 3.0 specification by combining data from several sources (Core Controller Classes, Database descriptions, Entities, ORM mappings). The main goal of this generator is to enable reverse API architecture, where we apply approach “Features/Code first, API specification later”. My role(s): Concept creator and developer.

Learn more about TimeTac company and products.

Results and benefits

Results of our API generator can be found at https://api.timetac.com

Firstly, we have reduced development time of API documentation for 100s of hours/year.

Secondly, we have generated 50k lines of API documentation completely automatically.

Thirdly, we have completely reduced number of manual mistakes and differences between documentation and actual API.

Moreover, we have migrated from Swagger 2.0 to OpenApi 3.0.0 and introduced new elements of the standard.

Finally, our customers are using our documentation daily, to learn about our API but also to generate code out of it. Yes, with our current documentation it is possible to generate frontend or backend skeleton code in various programming languages.

Details of the actual implementation, rules and source code is considered business important value and can not be shared publicly.

However, API documentation itself is publicly available for use and examination at https://api.timetac.com