Import RESTful Requests from Swagger 2.0 in Katalon

Introduction

Hello Ninjas! How’s the learning going? Well, In this article, We will gain an understanding of Swagger (Open API 2.0) and How to import Restful requests from Swagger 2.0 in Katalon Studio. So, get ready to learn something new and practical. Let’s begin, shall we?

What is Swagger?

We will begin by getting our concepts straight about Swagger, the Basic Structure of a Swagger File, and some commonly used Swagger Tools.

So, Swagger is a specification that provides a set of rules to describe and document the RESTful APIs. Alternatively, Swagger is an open-source framework used to design and describe API. It is also referred to as Open API 2.0. The version Swagger 1.1 was released in 2012, and after some revisions, 2014 marked the release of Swagger 2.0.

Basic Structure of Swagger File

Swagger can be written in JSON or YAML, but it is recommended to write it in YAML as it is easier to understand.

#metadata
swagger: "2.0"
info:
  title: TEST API
  description: API description goes here
  version: 1.0.0
#base URL
host: api.example.com
basePath: /base
schemes:
  - https
#paths
paths:
  /articles:
    get:
      summary: Returns a list of articles.
      description: Description of articles
      produces:
        - application/json
      responses:
        200:
          description: OK

Metadata

Metadata contains the Swagger version which defines the overall structure and representation of an API specification, the API info which consists of title and description(optional and can be multiline), and the version. Info can also have fields that specify license and contact information.

swagger: "2.0"
info:
  title: TEST API
  description: API description goes here
  version: 1.0.0

Base URL

The base URL for the API calls is defined with the help of schemes, host, and basePath:

host: api.example.com
basePath: /base
schemes:
  - HTTPS

All the API paths are relative to the base URL. For example, if ‘ /base ’ is the base path,  ‘/articles’ refer to https://api.example.com/base/articles. 

Consumes, Produces

The 'consumes' section and 'produces' section define the MIME types supported by the API. 

consumes:
  - application/json
  - application/xml
produces:
  - application/json
  - application/xml

Paths

The ‘paths’ section specifies the paths in your API, and the HTTP methods supported by the endpoints. For e.g., GET /articles can be described as

paths:
  /articles:
    get:
      summary: Returns a list of articles.
      description: Description of articles
      produces:
        - application/json
      responses:
        200:
          description: OK
 

Parameters

The Operations have parameters which can be passed through the URL path (e.g. ‘/articles/{articleId}’, query string- ‘/articles?role=admin’, headers (X-CustomHeader: Value), and the request body.

paths:
  /articles/{articleId}:
    get:
      summary: Returns an article by ID.
      parameters:
        - in: path
          name: articleId
          required: true
          type: integer
          minimum: 1
          description: Parameter description
      responses:
        200:
          description: OK
 

Responses

For each operation, various possible status codes are defined, such as ‘200 OK’ or ‘404 Not Found’, and the schema of the response body. Schemas can be either defined inline or can be referenced from an external definition via ‘$ref’ .

paths:
  /articles/{articleId}:
    get:
      summary: Returns an article by ID.
      parameters:
        - in: path
          name: articleId
          required: true
          type: integer
          minimum: 1
          description: The ID of the article to return.
      responses:
        200:
          description: An Article object.
          schema:
            type: object
            properties:
              id:
                type: integer
                example: 101
              name:
                type: string
                example: Introduction-to-Programming
        400:
          description: The specified article ID is invalid
        404:
          description: An article with the specified ID was not found.
        default:
          description: Unexpected error

Input and Output Models

The global definitions section lets you define common data structures used in your API. They can be referenced via $ref whenever a schema is required – both for the request body and response body. For example, this JSON object:

{
  "id": 101,
  "name": "Introduction-to-Programming"
}

The above can be represented as:

definitions:
  Article:
    properties:
      id:
        type: integer
      name:
        type: string
    #Both properties required
    required:  
      - id
      - name

Then, it can be referenced in the request body schema and response body schema as follows:

paths:
  /articles/{articleId}:
    get:
      summary: Returns an article by ID.
      parameters:
        - in: path
          name: articleId
          required: true
          type: integer
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/Article'
  /articles:
    post:
      summary: Creates a new article.
      parameters:
        - in: body
          name: article
          schema:
            $ref: '#/definitions/Article'
      responses:
        200:
          description: OK
 

Authentication

The 'securityDefinitions' and ‘security’ keywords are used to describe the authentication methods referred to in the API.

Various authentication methods that are supported are mentioned below:

• API Key
• Basic Authentication
• OAuth 2 common flows (implicit, password, application, and access code)

Swagger Tools

Let us now discuss the Swagger tools. With open source and professional toolset, Swagger tools help simplify development for individual users and teams. Let's take a look at them:

SwaggerHub

This platform is useful to teams and individuals to design and documentation of API with openAPI specification

Swagger Editor

It’s an API editor for the users to design APIs with openAPI specification.

Swagger UI

Swagger UI helps users to visualize the open API specification in an interactive UI

Swagger Codegen

It generates server stubs and client software development kits from the OpenAPI Specification.