Domain specific language for creating API documentation

Abstract

This article introduces a Domain-Specific Language (DSL) designed for the management and display of API documentation, aiming to ease the documentation process and enhance the quality of API guides. The common approach to documenting APIs often involves manual processes that are time-consuming and vastly different across different sources, because of the variety in either company practice or industry standards. The proposed DSL addresses these challenges by offering a structured, simple format to understand the complexities involved in describing API endpoints, parameters, request and response models, and perhaps even examples of such use. The main goal of this work lies in understanding and getting rid of the struggles developers face when having to deal with new API documentation. The specific aim of the DSL is to allow for quick adaptation by developers and technical writers without requiring extensive, dreadful research and understanding of the different interfaces and classifications of various sources. By combining theoretical design principles and practical implementation strategies, this work aims to demonstrate the effectiveness of using a DSL for API documentation. It will provide a comprehensive solution that will reduce the effort needed for using and understanding API documentation, by making it more consistent and accurate, therefore enhancing developer experience when having to use APIs.