Analysis of tools for REST contract specification in swagger/OpenAPI

Abstract

REST is a resource-based architectural style that has emerged as a promising way for designing Web services. A REST API exposes services’ functionalities through a contract that allows consumption by different clients. The contract specifies service’s request and response schemes and related rules the service and the client should comply with. The process of documenting and keeping an API consistent is a time consuming human effort. The documentation should reflect the implementation which may evolve. This work compares different tools for REST APIs specifications. We focused on tools that automatically generate Swagger (Open API in version 3.0), a specification for designing REST APIs. We evaluated the tools using a set of criteria whose results may help software engineers to choose the most appropriate tool, and point out gaps for research initiatives.