Analysis of Tools for REST Contract Specification in Swagger/OpenAPI

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.

[1]  Rennay Dorasamy.  API Design , 2021, API Marketplace Engineering.

[2]  Balaji Varanasi,et al.  Introduction to REST , 2021, Spring REST.

[3]  Xavier Blanc,et al.  Automated Generation of REST API Specification from Plain HTML Documentation , 2017, ICSOC.

[4]  Reza Malekian,et al.  Improving northbound interface communication in SDWSN , 2017, IECON 2017 - 43rd Annual Conference of the IEEE Industrial Electronics Society.

[5]  Frank Leymann,et al.  A Framework for the Structural Analysis of REST APIs , 2017, 2017 IEEE International Conference on Software Architecture (ICSA).

[6]  Mahesh Jethanandani,et al.  YANG, NETCONF, RESTCONF: What is this all about and how is it used for multi-layer networks , 2017, 2017 Optical Fiber Communications Conference and Exhibition (OFC).

[7]  Vijay Surwase,et al.  REST API Modeling Languages - A Developer's Perspective , 2016 .

[8]  Murat Yener,et al.  Model View Controller Pattern , 2014 .

[9]  Andy Zaidman,et al.  Web API growing pains: Stories from client developers and their code , 2014, 2014 Software Evolution Week - IEEE Conference on Software Maintenance, Reengineering, and Reverse Engineering (CSMR-WCRE).

[10]  Wu Chou,et al.  Design and Describe REST API without Violating REST: A Petri Net Based Approach , 2011, 2011 IEEE International Conference on Web Services.

[11]  Ivar Jacobson,et al.  The unified modeling language reference manual , 2010 .

[12]  José Ignacio Panach,et al.  Model-Driven Development , 2008, Informatik-Spektrum.

[13]  Ivar Jacobson,et al.  Unified Modeling Language Reference Manual, The (2nd Edition) , 2004 .

[14]  Isabel Azevedo,et al.  Dynamic Generation of Documentation, Code, and Tests for a Digital Marketing Platform's API , 2019, Advances in Computer and Electrical Engineering.

[15]  Ervin Varga,et al.  Documenting REST APIs , 2016 .

[16]  Robert Wideberg,et al.  RESTful Services in an Enterprise Environment : A Comparative Case Study of Specification Formats and HATEOAS , 2015 .

[17]  Dimitris Askounis,et al.  Community-based API Builder to manage APIs and their connections with Cloud-based Services , 2015, CAiSE Forum.

[18]  Sam Newman,et al.  Building microservices - designing fine-grained systems, 1st Edition , 2015 .

[19]  Martin P. Robillard,et al.  What Makes APIs Hard to Learn? The Answers of Developers , 2011 .

[20]  Nicolai M. Josuttis,et al.  Soa In Practice The Art Of Distributed System Design , 2007 .

[21]  Roy Fielding,et al.  Architectural Styles and the Design of Network-based Software Architectures"; Doctoral dissertation , 2000 .