Analysis of Tools for REST Contract Speciﬁcation in Swagger/OpenAPI

essica Soares Dos Santos

, Leonardo Guerreiro Azevedo, Elton F. S. Soares, Raphael M. Thiago

and Viviane T. Silva

IBM Research, Pasteur Ave, 146, Rio de Janeiro, Brazil

Keywords:

REST Services, REST Contracts, REST APIs, 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 speciﬁes 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 reﬂect the implementation which may evolve. This work compares different tools

for REST APIs speciﬁcations. We focused on tools that automatically generate Swagger (Open API in version

3.0), a speciﬁcation 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 INTRODUCTION

The design of an Application Programming Interface

(API) creates its contract (the API speciﬁcation) (San-

tos et al., 2019), i.e., its functionalities, the commu-

nication protocol, input and output parameters, data

format and endpoints (De, 2017).

The Representational State Transfer

(REST) (Fielding and Taylor, 2000) is an archi-

tectural style designed to address the properties for a

modern Web architecture. REST style deﬁnes a set

of constraints/principles that services must follow in

order to achieve usability, simplicity, scalability, and

extensibility (Li and Chou, 2011).

The REST APIs have established a means for real-

izing distributed systems (Haupt et al., 2017); hence,

it entails the importance of documenting REST APIs

in a proper way (Li and Chou, 2011). Keeping an API

documentation/contract aligned with the implementa-

tion is a challenging task due to services frequent up-

date (De, 2017). It is still an open issue how to im-

prove API design (Haupt et al., 2017), and one way

towards this is the use of tools for API contract gen-

eration during API development (Santos et al., 2019).

There are two approaches for documenting APIs

(Varga, 2016): (i) bottom-up or contract-last; (ii) top–

down or contract-ﬁrst. The former consists in gen-

erating the contract from the code, i.e., ﬁrst the

https://orcid.org/0000-0001-5082-4583

code is implemented and then the contract is cre-

ated/generated, e.g., marking up the code with annota-

tions and generating the API contract based on them.

The latter creates the API documentation/contract be-

fore writing the service code. Several speciﬁcations

have been proposed for specifying REST contracts,

such as: Swagger (or OpenAPI in its third version)

WADL

, WSDL2.0

, and API Blueprint

Swagger is the most popular language for spec-

ifying REST contracts (Tsouroplis et al., 2015), it

provides development tools, and it can be used for

bottom-up or top-down contract speciﬁcation.

This work aims at exploring tools that automat-

ically generate contract speciﬁcation. Technically, it

provides a description and a comparison of tools; help

software designers to identify relevant characteristics

to be considered when looking for a tool to document

REST services. Academically, it presents a back-

ground for one (starting) working in the area; point

out gaps for future researches.

The remainder of this work is organized as fol-

lows. Section 2 and Section 3 present background and

related work. Section 4 describes the tools, and Sec-

tion 5 compares them. Finally, Section 6 concludes

and points out future work.

http://swagger.io

https://www.w3.org/Submission/wadl/

https://www.w3.org/TR/2007/REC-wsdl20-20070626

http://raml.org

Santos, J., Azevedo, L., Soares, E., Thiago, R. and Silva, V.

Analysis of Tools for REST Contract Speciﬁcation in Swagger/OpenAPI.

DOI: 10.5220/0009381202010208

In Proceedings of the 22nd International Conference on Enterprise Information Systems (ICEIS 2020) - Volume 2, pages 201-208

ISBN: 978-989-758-423-7

201

2 BACKGROUND

RESTful services must follow six main principles

(Varanasi and Belida, 2015), (Fielding and Taylor,

2000): (i) Clear separation of client and server con-

cerns; (ii) Stateless communication; (iii) Server re-

sponses must be declared if are cacheable; (iv) Ser-

vices should have a uniform interface; (v) Intermedi-

ate layers of software or hardware can be introduced

between client and server; (vi) Client may download

code from server and execute it.

2.1 REST API

An API provides a set of functionalities, their descrip-

tions and dictates the rules for using them. APIs are

responsible for opening a system/set of services for

a broader audience and can make integration easier

(Preibisch, 2018).

A process for service implementation (and con-

tract design) may be composed by the following

steps (Josuttis, 2007) (Figure 1

1. Create a requirement sketch: e.g., in pseudocode,

sequence diagram or use case description aiming

at understanding the business needs;

2. Create a speciﬁcation of the service: e.g., an UML

design model or a Swagger speciﬁcation;

3. Search for potential services, i.e., existing ser-

vices that may ﬁt the requirement, which may re-

sult in:

(a) A service that ﬁts the new requirement, which

can be used directly, and the process ends;

(b) A service that partially ﬁts the new require-

ment, which may be refactored - service clients

may be impacted;

a new service should be developed.

4. Search for existing type deﬁnitions to be used as

input/output parameters of the service. Types may

be created or changed.

Using a tool for contract speciﬁcation may help

depending on the approach the tool supports (i.e.,

contract-ﬁrst or contract-last). In the former, the ser-

vice contract may be created in Step 2 and used in the

search for potential service (Step 3) and the search for

types (Step 4). In the latter, a tool for contract genera-

tion creates it after the implementation is done; hence,

it does not help much the presented process.

A REST API should describe (Cao et al., 2017):

a base URL corresponding to a common preﬁx of

The model was designed in a UML activity dia-

gram (Rumbaugh et al., 2004) model.

Figure 1: A Process for Service Implementation.

all other URLs that give access to the resources; a

path template describing how the base URL should

be completed to provide access to a given resource;

supported actions, i.e., HTTP methods; parameters

needed to each pair path template-method.

2.2 Swagger 2.0/OpenAPI

Swagger is a framework for documenting REST

APIs

. It has a large community of users and sup-

porters, and it can be written in JSON

or in YAML

Swagger main elements are (OpenAPI initiative,

2018): (i) Swagger version; (ii) API title, version

and description; (iii) API server’s address; (iv) Paths

and available HTTP methods (POST, GET, PUT,

DELETE); (v) The operations’ request parameters

and responses; (vi) Possible return HTTP status code;

(vii) Type deﬁnitions (also called API models). In

December 2017, Swagger version was updated to

3.0 and renamed to OpenAPI Speciﬁcation. Be-

yond structural changes, the main differences be-

tween Swagger 2.0 and 3.0 are: (i) Version property

changed to openapi; (ii) New keywords for schema

speciﬁcation/validation, such as: oneOf, anyOf, not,

allOf ; (iii) Each endpoint may have several addresses;

(iv) Speciﬁcation of links between resources follow-

ing HATEOAS; (v) Speciﬁcation of examples.

An example is presented at https://petstore.swagger.io/

v2/swagger.json.

JavaScript Object Notation (https://www.json.org)

YAML Ain’t Markup Language (http://yaml.org)

ICEIS 2020 - 22nd International Conference on Enterprise Information Systems

202

3 RELATED WORK

The majority of work compares existing speciﬁca-

tion languages for documenting service contracts or

presents guidelines/recommendations to be followed

when developing service contracts. Our work differs

from them since we analyze tools for generation and

maintenance of REST contracts written in Swagger.

Wideberg (Wideberg, 2015) presented a compari-

son of different speciﬁcation formats for REST con-

tracts, such as: Swagger, RAML, API Blueprint and

WADL. The work concluded that Swagger is the

speciﬁcation language that most suits the desirable re-

quirements in enterprise environments and the spec-

iﬁcation language that has the most active commu-

nity, which is a good indicator of future support and

continuous development. Similarly, Surwase (Sur-

wase, 2016) analyzed the same speciﬁcation lan-

guages from a developer’s perspective, and pointed

out that Swagger and RAML support many program-

ming languages adopted in the industry. Among the

dimensions used for comparing the speciﬁcation lan-

guages, it was considered the output format that can

be generated (YAML, Markdown and JSON) by the

speciﬁcations and the companies that are the sponsors

of these languages.

Pritchard et al. (Pritchard et al., 2017) com-

pares the same languages that were considered by

(Wideberg, 2015) and (Surwase, 2016), but includ-

ing RESTCONF (Jethanandani, 2017) and WSDL 2.0

languages. They remark the objectives of each lan-

guage, compared their output format, and highlighted

their drawbacks and advantages. As Swagger advan-

tages, they pointed out, e.g.,: vast development docu-

mentation; good community support; the possibility

to be adopted by existing APIs; and, to be written in-

dependently of speciﬁc programming language. The

lack of API testing interaction is its main drawback.

Robillard (Robillard, 2009) investigated chal-

lenges that software developers can face when learn-

ing new APIs. He pointed out a set of guidelines that

API documentations must follow in order to be easy

to learn and use. These guidelines include: be com-

plete; present good examples; provide support to

complex usage scenarios; and, be conveniently or-

ganized. In the same sense, Espinha et al. (Espinha

et al., 2014), from interviews with developers, pro-

duced a set of recommendations API designers should

follow in order to reduce the impact API clients face

when the API evolves, such as: provide examples de-

scribing the usage of the new version functionalities;

and, adopt and execute blackout tests, which consists

in deactivating older versions of the API for short pe-

riods of time before deactivating it permanently.

4 TOOLS FOR SWAGGER

GENERATION

Many tools have been proposed as alternatives to fa-

cilitate the Swagger generation and maintenance. In

this section, we present a brief description of them.

Our goal is not to present and extensive list of all ex-

isting tools, but rather tools that represent different

perspectives of development, such as tools that gen-

erate code (and Swagger) from models, tools that al-

low generation of Swagger from code through annota-

tions, tools that work apart from code and model etc.

The tools were selected based on the following char-

acteristics: Availability for download; Adoption by

the industry; Provide documentation or usage exam-

ples that allows to understand their features.

4.1 Tools Provided by Swagger Project

The Swagger project provides three ofﬁcial open-

source tools:

1. Swagger Editor: an API Editor for designing

Swagger contracts. It can be downloaded and

used locally or can be accessed online

;

2. Swagger UI: It automatically generates an

HTML page from a Swagger speciﬁcation, pro-

viding an interactive interface to visualize and test

Swagger speciﬁcations that can be accessed by the

Web Browser;

3. Swagger Codegen: it generates client and server

code from Swagger, e.g., in Java, Python and PHP.

4.2 Visual Paradigm

Visual Paradigm

(VP) is a software engineering tool

for modeling/designing software. This tool focuses

on the Model Driven Development (MDD) (Pastor

et al., 2008) approach, which consists in generating

the software from the software model that speciﬁes

how it should work instead of starting from writing

code. By using VP, it is possible to design a REST

API by designing class diagrams that describe REST

resources. The VP UML component called REST re-

source can be associated with a URI (resource iden-

tiﬁer), request and response bodies (with HTTP sta-

tus), path parameters, and a method that speciﬁes the

resource action.

The process of designing/documenting a RESTful

API is totally graphical. Given a UML class diagram

that describes REST service deﬁnitions, the VP API

http://editor.swagger.io/

https://www.visual-paradigm.com/

Analysis of Tools for REST Contract Speciﬁcation in Swagger/OpenAPI

203

designer is able to automatically generate API deﬁni-

tions in accordance with Swagger 2.0. Default UML

relationships can be deﬁned between UML classes,

such as, inheritance, association, multiplicity. Addi-

tionally, it is possible to generate from the diagrams:

(i) the server code, which is the HTML code that

shows how the API should be consumed; and, (ii)

the client and servlet code, which corresponds to the

code for a client to consume an API service and the

code that a service provider should have to be able

to process a client request, respectively. Code can be

generated in programming languages like Java, An-

droid, Obj-C, JavaScript, C#, PHP, Perl, Python. Vi-

sual REST API designer is available in the Enterprise

and Professional editions of Visual Paradigm.

4.3 IBM Rational Software Architect

Designer

IBM Rational Software Architect

(RSA) Designer

is a MDD software engineering tool for the develop-

ment and design of applications and Web services.

RSA supports the generation of Swagger from

UML diagrams and provides also some kinds of trans-

formations that convert Swagger speciﬁcations into

REST models (i.e., reverse engineering). In this way,

it is possible to load and visualize existing Swagger

ﬁles in the form of UML diagrams.

RSA allows conversion of REST models into code

representing the skeleton of the service code, e.g., in

Java, NodeJS, C#. It supports only Swagger 2.0.

4.4 Typson

The Typson

library converts Typescript deﬁnitions

to JSON-schemas which can be integrated with Swag-

ger deﬁnitions and referenced as input or output pa-

rameter types. It supports types, e.g., required prop-

erties, inheritance , and enumerations.

When Typson converts the Typescript deﬁnitions

to JSON-schemas, it discards the explicit inheritance

information, i.e., when a Typescript interface A ex-

tends an interface B, the attributes of B are copied to

A and the relationship between A and B is not main-

tained. The advantages of using Typson are: it pro-

vides the reuse of interfaces by different methods and

by other interfaces (when one interface extends an-

other one); the set of interfaces does not need to be

organized inside the same ﬁle; and, the API docu-

mentation is coupled with a Typescript code but the

https://www.ibm.com/us-en/marketplace/rational-soft

ware-architect-designer

https://github.com/lbovet/typson

service code is not coupled with any speciﬁc program-

ming language. It also may help the integration with

UI (User Interface) programming when both UI and

services use the same type. Typson supports Swagger

2.0 and is available as a Node.js module.

4.5 Flask-RESTPlus

Flask RESTPlus

is an extension of Flask, a frame-

work for developing Python applications. The REST

documentation is generated based on a set of prede-

ﬁned decorators that are used to relate a method to

an endpoint, input and output parameters. By default,

Flask-RESTPlus generates automatically Swagger UI

documentation. Method responses are speciﬁed with

the decorator @api.response. Flask-RESTPlus has

a builtin mechanism to validate request data. By

importing reqparse, one can associate a parame-

ter with a primitive type (for instance, type int).

The reqparse provides a RequestParser that is able

to show error messages by itself. Flask-RESTPlus

also allows the deﬁnition of API models with the

api.model, which represents type deﬁnitions, i.e., ob-

jects with a set of attributes that can be passed as

the payload of the method (input or output param-

eters). The types, descriptions, and other informa-

tion (e.g., attribute required or not) about attributes

of an object can be speciﬁed when importing ﬁelds

from flask restplus. Inheritance can be speci-

ﬁed between API models of the Flask-RESTPlus and

API models can be nested inside existing models.

Additionally, models can be extended by using the

api.inherit() method.

4.6 Flasgger

Flasgger

14,15

is a Flask extension that is able to ex-

tract Swagger from Flask code. Flasgger provides an

interactive API documentation. Swagger is generated

based on decorators and docstrings that should be put

inside the service code. The decorators are used to

deﬁne the routes @app.route, which inform the path

of the service endpoints and the HTTP methods that

represents the operations. The docstrings are used to

deﬁne input/output parameters, type deﬁnitions and

responses. Flasgger allows speciﬁcations be deﬁned

in an external Swagger ﬁle and related to the code us-

ing an speciﬁc decorator called (swag from) or a doc-

string ﬁle shortcut. Flasgger is totally compatible with

the generation of Swagger 2.0 and previous versions.

https://github.com/noirbizarre/ﬂask-restplus

https://github.com/rochacbruno/ﬂasgger

http://ﬂasgger.pythonanywhere.com

ICEIS 2020 - 22nd International Conference on Enterprise Information Systems

204

Documentations states OpenAPI is also supported but

we did not ﬁnd examples showing this.

4.7 Flask-Restful-Swagger

The Flask-Restful-Swagger

supports Swagger by

wrapping the API instance and including decorators

in a Python code. It provides a swagger generator

and a graphical interface of the services that are ex-

posed. The decorator @swagger.operation is respon-

sible for deﬁning an operation with a set of parame-

ters and response (e.g., datatype, multiplicity, name,

description). Methods that are not decorated with

@swagger.operation are not added to Swagger doc-

umentation as operations. Classes can be decorated

with @swagger.model in order to represent a Swag-

ger type deﬁnition. Instead of using the decorator

@swagger.model, it is also possible to use the dec-

orator @marshal with passing the class to deﬁne a

Swagger type deﬁnition. Additionally, metadata can

be passed to the Swagger by creating a swagger.docs

ﬁle containing the description of the endpoints, api

version, base path and so on.

4.8 Spring MVC REST API

Spring

is a Java framework that can be used

to build Web applications following the Model-

View-Controller (MVC) architectural pattern (Sha-

ran, 2015). Spring MVC provides many advantages,

such as dependency injection model

and modules to

facilitate data access.

The REST API support was introduced in Spring

3.0. The Spring MVC REST API

is able to generate

a Swagger speciﬁcation based on a set of predeﬁned

annotations that should be included in the Java code.

First of all, a Swagger conﬁguration should be deﬁned

for the Java project in a XML ﬁle. REST endpoints

are deﬁned by annotating classes with the @Api anno-

tation. The annotators are: (i) @Api: indicates a class

as a Swagger class; (ii) @ApiOperation: indicates the

responsibility of the method; (iii) @ApiParam: cor-

responds to the parameter that the method is expect-

ing and can be associated with its name, value, de-

scription and a ﬂag; (iv) @ApiResponse: represents

the response; and, (v) @ApiModel: used to deﬁne a

Swagger type deﬁnition. In order to accelerate the

code documentation, there are tools that generate doc-

umentation from code. The Springfox

has this pur-

https://github.com/andyzt/ﬂask-restful-swagger

https://spring.io/

http://martinfowler.com/articles/injection.html

https://spring.io/projects/spring-restdocs

http://springfox.github.io/springfox

pose. It is a suite of Java libraries that generates speci-

ﬁcations for JSON APIs written using the Spring fam-

ily of projects. Springfox examines an application at

runtime and infers semantics based on Spring conﬁg-

urations, class structures and compile time Java An-

notations. It generates speciﬁcations such as Swag-

ger, RAML and jsonapi. It has the goal to discourage

using (swagger-core) annotations that are not used

at runtime. It provides options to conﬁgure general

characteristics, and one has to use swagger-core an-

notations when a speciﬁc documentation is needed.

Hence, it does not replace the annotation use although

it speeds up the documentation process. Therefore,

we evaluated, in this work, the Spring MVC which is

more general.

4.9 Swagger PHP

The Swagger PHP tool

scans a PHP project and

merge all annotations in order to generate a Swag-

ger ﬁle. A Swagger POST operation is deﬁned

by including the @SWG\Post annotation. Simi-

larly, there are equivalent annotations for other HTTP

methods (GET, PUT, DELETE). Inside an annota-

tion of an operation, it is possible to inform the path,

the id of the operation and the operation descrip-

tion. Additionally, Swagger PHP provides an anno-

tation called @SWG\Info to deﬁne the description

and version of the API. @SWG\Parameter should

be nested inside an annotation of operation and in-

dicates the parameter type, description and if it is re-

quired or not. The annotation @SWG\Response rep-

resents the operation response and deﬁnes the sta-

tus, the description and the type. Responses also

should be nested inside an annotation of operation.

Type deﬁnitions can be speciﬁed using the annota-

tion @SWG\Deﬁnition. Deﬁnitions can be referenced

with the annotation @SWG\Schema. In this way,

these deﬁnitions can be referenced and reused in dif-

ferent parts of the code. The keyword allOf can be put

inside a @SWG\Deﬁnition in order to create a combi-

nation of deﬁnitions. The documentation of Swagger

PHP states that it is able to generate Swagger in the

most recent version, i.e., Swagger (Open API) 3.0 and

already can deal with anyOf and oneOf keywords.

However, there is a lack of examples involving an-

notations that generate Swagger 3.0. The majority of

annotations to generate Swagger 3.0 are similar to the

annotations for generating Swagger 2.0, but the preﬁx

@SWG is replaced by the preﬁx @OA.

https://github.com/zircote/swagger-php

Analysis of Tools for REST Contract Speciﬁcation in Swagger/OpenAPI

205

5 COMPARATIVE ANALYSIS

This section presents a comparative analysis of the

tools. The evaluation criteria are presented in Ta-

ble 1. They were deﬁned according to what a tool

should support to create contracts with the formal-

ism required by service development initiatives as

proposed by OpenAPI project (OpenAPI initiative,

2018). Besides, we added criteria MDD support and

the approach (contract-ﬁrst or a contract-last).

Table 1: Comparison criteria.

Description

1 Ability to generate Swagger automatically

2 Ability to generate client or server code

3 Ability to generate UI documentation

4 Model Driven Development approach

5 Support to inheritance, reuse and validation

6 Low coupling with service code

7 Ability to check Swagger version syntax

8 Support to OpenAPI (Swagger version 3)

9 Contract-ﬁrst or contract-last approach

Table 2 presents the evaluation. Criteria 7, 8 and 9 are

not mentioned in Table 2 due to space limitations for

the table presentation. However, a discussion about

all criteria is presented as follows.

Criterion 1: Swagger codegen and Swagger UI are

not able to generate Swagger speciﬁcation ﬁle. Al-

though the Swagger editor tool also does not present

means to automatize Swagger generation, it can fa-

cilitate the manual creation of the Swagger speciﬁ-

cation ﬁle because it presents Swagger examples and

can receive as input a Swagger speciﬁcation and in-

form if its syntax is correct according to the Swagger

version, highlighting errors. Typson tool is able to

generate API models (deﬁnitions) using Typescript,

but the information about the endpoints (e.g., input

and output parameters) has to be provided manually

inside the Swagger ﬁle (in JSON or YAML). In Table

2, the sixth column (Based on) indicates the way that

the tools whose column Generate Swagger is (X) use

to address Criterion 1.

Criterion 2: VP and Swagger codegen present the

ability to generate server and client code, the IBM

RSA can only generate server code. In Table 2, the

column Based on indicates the way the tool which

column Generate Client Code or Generate Server

Code marked with (X) use to address Criterion 2.

Criterion 3: An UI allows users to visualize the

resources/operations that are available, the expected

input parameters and responses, and try out the in-

vocation of different operations on the resources.

VP, Flask-RESTPlus, Flask-Restful-Swagger, Flasg-

ger and Swagger UI can generate an HTML page

based code exposing the interface of the services. Ap-

proaches that do not provide the generation of a spe-

ciﬁc UI Documentation can be combined with the

Swagger UI ofﬁcial tool as is the case of, e.g., Typ-

son, Swagger PHP and Spring MVC REST API. In

Table 2, the column Based on indicates the way that

the tool which column Generate UI Documentation is

marked with (X) use to address Criterion 3.

Criterion 4: VP and IBM RSA are based on the

MDD approach, providing mechanisms to generate

Swagger from diagrams, and a graphical way to edit

and visualize the Swagger speciﬁcations and Swag-

ger type deﬁnitions (API models). In this approach,

it is not required that service contract designers have

programming abilities. Additionally, IBM RSA is the

only one that can directly load existing Swagger spec-

iﬁcations into UML diagrams – reverse engineering.

Criterion 5: Swagger deﬁnitions are objects that can

be referenced as input and output parameters of oper-

ations. In Table 2, the column API Model Inheritance

shows that, by using Flasgger and Swagger Editor, it

is possible to associate a deﬁnition using a keyword

(e.g., allOf ). In VP and IBM RSA the inheritance

is represented using inheritance UML relationships.

The column API model Reuse corresponds to the abil-

ity to reference an API model inside another one or in

different operations. The column Validate Input Data

exhibits whether the approach provide own mecha-

nisms for validating input data against Swagger spec-

iﬁcation. E.g., Flask-RESTPlus provides reqparse li-

brary for that.

Criterion 6: Flask-RESTPlus, Flask-Restful-

Swagger, Spring MVC Rest API and Swagger

PHP, generates speciﬁcations based on annota-

tions/decorators provided inside the service code.

Flasgger generates the speciﬁcation based on

docstrings inside the code. Although annota-

tions/docstrings can be deﬁned before the complete

implementation of the service, they need to be put

inside the service code. Therefore, VP, IBM RSA

and Typson are the only tools that automatize the

Swagger generation and Swagger Editor allows the

edition of the contract decoupled form the code.

They are completely independent of the technology

that will be used to implement the services, i.e.,

they can be adopted by software groups that desire

to implement services in different programming

languages.

Criterion 7: Swagger editor is the only tool that is

able to verify whether a Swagger speciﬁcation is in

accordance with the syntax of a given Swagger ver-

sion. This feature can be very helpful to the ones that

want to edit parts of the REST APIs manually.

Criterion 8: Only the ofﬁcial tools (Swagger code-

ICEIS 2020 - 22nd International Conference on Enterprise Information Systems

206

Table 2: Tools Analysis Summary.

Criterion 1 Criterion 2 Criterion 3 Criterion 4 Criterion 5 Criterion 6

Tool

Generate

Swagger

Generate

Client

Code

Generate

Server Code

Generate

Documentation

Based on

Generate Swagger

from Model

Generate Model

from Swagger

API Model

Inheritance

API Model

Reuse

Validate Input

Data

Low Coupling

with Service

Code

VP X X X X UML Diagram X UML Relationship X X

IBM RSA X X UML Diagram X X UML Relationship X X

Flask-RESTPlus X X Decorators Method X X

Flask-RESTful-Swagger X X Decorators Decorator X

Flasgger X X

Decorators

Docstring

Swagger

keyword

X X

Swagger editor

Swagger

keyword

Swagger codegen X X

Swagger

speciﬁcation

Swagger UI X

Swagger

speciﬁcation

Spring MVC REST API X Annotations Annotation X X

Typson X

Typescript

deﬁnitions

Typescript

keyword

X X

Swagger PHP X X Annotations Annotation X

gen, Swagger UI and Swagger Editor), Flasgger and

the Swagger PHP support the current version of

Swagger 3.0 (OpenAPI). However, it is not clear in

the documentation of Flasgger and Swagger PHP if

they support all new features of the Swagger 3.0.

Criterion 9: All tools based on annotating the code

follow contract-last approach. Swagger Editor is a

tool for creating the contract; therefore, it may be used

on a contract-ﬁrst approach. MDD tools (like VP and

IBM RSA) generates code from model; hence, they

are contract-ﬁrst tools since the contract is deﬁned by

the model. These tools support better the process for

service contract design (Figure 1).

6 CONCLUSIONS

The REST architectural style has become a popu-

lar approach for development in Service-Oriented Ar-

chitecture (SOA) and in Microservice Architecture

(MSA), in which applications are organized into sev-

eral independent services (Newman, 2015). REST

style is centered in the idea of transferring data (re-

sources) through the use of HTTP methods in a state-

less way, and deﬁnes a set of desirable principles/

good practices to be followed when building modern

Web Services. Systems based on REST style can ex-

pose their services to be consumed via REST APIs.

Several speciﬁcation languages have been pro-

posed to document REST services. In this research,

we focused on Swagger since it is: the most popular

framework for documenting REST APIs (Tsouroplis

et al., 2015); the language that most suits the desir-

able requirements in enterprise environments (Wide-

berg, 2015); and, highly adopted in the industry

(Scherer, 2016). Many tools have been proposed to

facilitate the creation and maintenance of Swagger

speciﬁcations.

In this work, we surveyed the literature in order

to ﬁnd tools that generate Swagger speciﬁcation, and

analyzed them considering their adherence to a set

of criteria the Swagger project presents as the advan-

tages of using such speciﬁcation and the best ﬁt to a

process for contract development.

The results of our comparative analysis are use-

ful to understand the features provided by each tool

and can help one to combine different tools. As

an example, Flasgger and Swagger UI can be com-

bined to obtain the UI documentation together with

the Swagger speciﬁcation ﬁle. Additionally, existing

Swagger speciﬁcation ﬁles generated by tools such as,

Flasgger or Typson, can be loaded into the IBM RSA

tool in order to achieve the graphical management of

REST contracts, what can facilitate the understanding

or refactoring of existing service speciﬁcations.

MDD tools best support the process for contract

development; however, they may not ﬁt all the crite-

ria for service development. E.g., the Visual Paradigm

meets almost all criteria except input data validation,

while IBM RSA does not meet this criterion besides

does not generate client code and neither UI docu-

mentation.

The tools provided by the Swagger Project lack

for one that generates the contract from a model, i.e.,

a more abstract representation. The initiative could

handle this feature in a new tool or researchers could

study the combination of existing tools and the Swag-

ger project tools to support it.

The tools based on annotations or decorators do

not generate client code nor Swagger speciﬁcation,

which they could support in new versions. They could

also support the creation of the annotations out of the

code in order to reduce this coupling (Criterion 6).

The automatic validation of input data against the

types and deﬁnitions presented in the Swagger spec-

iﬁcation is a feature that should be better explored in

future tools. The automatic validation of input data

is a crucial factor due to security issues (Sudhakar,

2011). Also, we have identiﬁed a lack of tools that

provide support to Swagger 3.0 (OpenAPI). Further-

more, considering the few tools that support it, there

is still a lack of examples illustrating their usage in-

Analysis of Tools for REST Contract Speciﬁcation in Swagger/OpenAPI

207

volving speciﬁc Swagger 3.0 features.

As other future work, we propose empirical eval-

uation of the contract-ﬁrst tools to the process for

contract speciﬁcation (Figure 1) and investigate how

contract-last tools could also support some of that

process activities. In other words, how the tools may

speed up and improve the quality of contract speciﬁ-

cation.

This work was a survey based on documentation

analysis; so, as future work, we intend to check our

ﬁndings by performing case studies using the tools in

practice.

Another direction of future work would be eval-

uate the documentation as a whole, and not only the

contract speciﬁcation, and its use in the development

lifecycle. It would include also other tools like Post-

man

ACKNOWLEDGEMENT

This project was executed under the Brazilian Na-

tional Petroleum Agency (ANP) R&D incentive reg-

ulatory framework.

REFERENCES

Cao, H., Falleri, J.-R., and Blanc, X. (2017). Auto-

mated Generation of REST API Speciﬁcation from

Plain HTML Documentation. In International Con-

ference on Service-Oriented Computing, pages 453–

461. Springer.

De, B. (2017). API Management: An Architect’s Guide to

Developing and Managing APIs for Your Organiza-

tion - API Documentation, pages 59–80. Apress.

Espinha, T., Zaidman, A., and Gross, H.-G. (2014). Web

API growing pains: Stories from client developers

and their code. In IEEE Conference on Software

Maintenance, Reengineering and Reverse Engineer-

ing (CSMR-WCRE), pages 84–93.

Fielding, R. T. and Taylor, R. N. (2000). Architectural

styles and the design of network-based software ar-

chitectures, volume 7. University of California, Irvine

Doctoral dissertation.

Haupt, F., Leymann, F., Scherer, A., and Vukojevic-Haupt,

K. (2017). A framework for the structural analysis of

REST APIs. In Software Architecture (ICSA), 2017

IEEE International Conference on, pages 55–58.

Jethanandani, M. (2017). Yang, netconf, restconf: What is

this all about and how is it used for multi-layer net-

works. In Optical Fiber Communication Conference,

pages W1D–1. Optical Society of America.

Josuttis, N. M. (2007). SOA in practice: the art of dis-

tributed system design. “’Reilly Media, Inc”.

https://www.postman.com/

Li, L. and Chou, W. (2011). Design and describe REST API

without violating REST: A Petri net based approach.

In 2011 IEEE International Conference on Web Ser-

vices (ICWS), pages 508–515. IEEE.

Newman, S. (2015). Building microservices: designing

ﬁne-grained systems. “O’Reilly Media, Inc.”.

OpenAPI initiative (2018). OpenAPI Speciﬁcation.

https://github.com/oai/openapi-speciﬁcation/blob/

master/versions/3.0.1.md.

Pastor, O., Espa

na, S., Panach, J. I., and Aquino, N.

(2008). Model-driven development. Informatik-

Spektrum, 31(5):394–407.

Preibisch, S. (2018). API Design. In API Development,

pages 41–60. Springer.

Pritchard, S. W., Malekian, R., Hancke, G. P., and Abu-

Mahfouz, A. M. (2017). Improving northbound inter-

face communication in SDWSN. In I Annual Confer-

ence of the IEEE Industrial Electronics Society, pages

8361–8366. IEEE.

Robillard, M. P. (2009). What makes APIs hard to learn?

Answers from developers. IEEE software, 26(6):27–

34.

Rumbaugh, J., Jacobson, I., and Booch, G. (2004). Uni-

ﬁed Modeling Language Reference Manual, The (2Nd

Edition). Pearson Higher Education.

Santos, R., Pereira, I., and Azevedo, I. (2019). Dynamic

Generation of Documentation, Code, and Tests for a

Digital Marketing Platform’s API. In Code Gener-

ation, Analysis Tools, and Testing for Quality, pages

1–35. IGI Global.

Scherer, A. (2016). Description languages for REST APIs-

state of the art, comparison, and transformation. Mas-

ter’s thesis, University of Stuttgart, Germany.

Sharan, K. (2015). Model-view-controller pattern. In Learn

JavaFX 8, pages 419–434. Springer.

Sudhakar, A. (2011). Techniques for securing rest. CA

Technology Exchange, 1:32–40.

Surwase, V. (2016). REST API Modeling Languages-A De-

veloper’s Perspective. International Journal of Sci-

ence Technology & Engineering, 2(10):634–637.

Tsouroplis, R., Petychakis, M., Alvertis, I., Biliri, E., and

Askounis, D. (2015). Community-based API Builder

to manage APIs and their connections with Cloud-

based Services. In CAiSE Forum, pages 17–23.

Varanasi, B. and Belida, S. (2015). Introduction to REST,

pages 1–13. Apress, Berkeley, CA.

Varga, E. (2016). Documenting REST APIs. In Creating

Maintainable APIs, pages 143–157. Springer.

Wideberg, R. (2015). Restful services in an enterprise en-

vironment - a comparative case study of speciﬁcation

formats and HATEOAS. Master’s thesis, Royal Insti-

tute of Technology, Stockholm, Sweden.

ICEIS 2020 - 22nd International Conference on Enterprise Information Systems

208