Swagger API

The goal of Swagger is to define a standard, language-agnostic interface to REST APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection.  When properly defined via Swagger, a consumer can understand and interact with the remote service with a minimal amount of implementation logic.  Similar to what interfaces have done for lower-level programming, Swagger removes the guesswork in calling the service.

 

Technically speaking - Swagger is a formal specification surrounded by a large ecosystem of tools, which includes everything from front-end user interfaces, low-level code libraries and commercial API management solutions.

 

To perform model-first design of a REST API using Swagger with Hackolade, you must first download the Swagger plugin.  This plugin is strictly compliant with version 2.0 of the OpenAPI specification.  Another plugin is required to support the OpenAPI 3.0 specification.

 

Creating APIs is not easy! And writing Swagger documentation in a design-first approach can be tedious at best, generally error-prone and frustrating...  Hackolade takes a visual schema-centric approach so you can focus on the content of requests and responses. The application also assists with all the metadata to produce validated Swagger files and test the transactions.  You can also reverse-engineer existing Swagger files in JSON or YAML to produce a graphical representation of your APIs.

Hackolade was specially adapted to support the API design of Swagger, including all the necessary metadata for the API, the requests and responses.  The application closely follows the terminology of the specification.  The visual tool puts the focus on what really matters in an API: the schema of the information being exchanged between systems.  At the same time, it provides assistance to modelers and does not require perfect mastery of the Swagger syntax.  It generates validated files that are syntactically correct and compatible with the specification thereby greatly improving productivity and quality.   A step-by-step tutorial is available in a YouTube video.

 

The diagram below results from the reverse-engineering of the Pet Store sample API.

 

Data Types

The Swagger specification describes primitives (or scalar) data types which can have an optional property modifier, format, plus a file primitive type.  Complex types such as arrays and sub-objects, plus combinations thereof, are also allowed.

 

       

 

 

API metadata

The info object, as well as the host, basePath, schemes, consumes, produces, the securityDefinitions object, the security object, the tags object, and externalDocs object are fixed fields treated as metadata and maintained at model-level in Hackolade.

    

 

Definitions

An object of schema objects with definitions of inputs and outputs to be produced and consumed by operations.  Data types can be objects, but also primitives and arrays. This object is based on the JSON Schema Specification Draft 4 and uses a predefined subset of it. On top of this subset, there are extensions provided by this specification to allow for more complete documentation.

 

 

Consult this page or more information on how to use definitions.  For Swagger, you should limit yourself to Hackolade model definitions.

Resource

The resource path object is a container representing the relative path to an individual endpoint.  The field name must start with a slash ("/").  The path is appended to the basePath in order to construct the full URL.  Path templating (usage of curly braces ("{}") to mark a section of a URL path as replaceable using path parameters) is allowed.

 

Each resource contains one or more "path item objects" made of a request and one or more responses:

 

You may create a new resource via right-click anywhere in the ERD view and choosing the contextual menu option:

 

or via the menu:

 

or the toolbar:

 

 

Requests

A request is an object with a type, associated data, relationships to other resources, and a set of methods that operate on it.  Only a few standard methods are defined for the resource (corresponding to the standard HTTP GET, POST, PUT and DELETE methods.)

 

The Parameter Object describes a single operation parameter defined by a combination of a name and location.  Hackolade provides a handy template of parameter types allowing the description of the payload either by adding adding individual fields or by referencing an existing definition.

 

 

 

To create a request within a resource container, you may:

- right-click inside the container area of the ERD pane, and choose the contextual menu option:

- choose the Action menu:

- choose the toolbar button:

 

It is easy to maintain the metadata for a request in the properties pane:

 

Responses

Response definitions describe responses from API operations.  For each request, you may create one or more responses. 

 

 

A response may have a schema that is defined as individual fields or references a definition:

 

To create a response for a given request, you may:

- right-click on the request in the ERD and choose the contextual menu option:

- or choose the Action menu:

- or choose the toolbar button:

 

It is easy to maintain the metadata for a response in the properties pane:

Forward-Engineering

The files describing the RESTful API in accordance with the Swagger specification are represented as JSON objects and conform to the JSON standards.  Hackolade generates Swagger documentation in JSON format or YAML format.  The schema exposes two types of fields. Fixed fields, which have a declared name, and patterned fields, which declare a regex pattern for the field name. Patterned fields can have multiple occurrences as long as each has a unique name.  The Swagger representation of the API is made of a single file. However, parts of the definitions can be split into separate files, at the discretion of the user. This is applicable for $ref fields in the specification as follows from the JSON Schema definitions.

 

The script can also be exported to the file system via the menu Tools > Forward-Engineering, or via the Command-Line Interface.

 

 

 

An internal Swagger syntax validator ensures that the generated file is valid, and the right-hand pane allows interactions with the API and testing. 

 

Reverse-Engineering

This function lets you take a Swagger file in JSON or YAML format and generate a Hackolade model.  Then, you may enrich the model with comments, generate standard Hackolade documentation, and make the API evolve to generate a new Swagger file through forward-engineering.

 

External references

It is possible to reference a variety of definitions created elsewhere:

- another Hackolade model

- a JSON Schema file

- an internet link url to a JSON Schema

- a Swagger API file (YAML or JSON)

- a Swagger domain export file (YAML or JSON)

- a SwaggerHub API url

- a SwaggerHub domain url

- a Polyglot data model