api2swagger-ext

Generate Swagger 2.0 (Open API) spec from Curl like API Call.

Installation

You can install api2swagger-ext either through npm or by cloning and linking the code from GitHub. This document covers the installation details for installing from npm.

Installation from npm

The api2swagger-ext module and its dependencies are designed for Node.js and is available through npm using the following command:

From a Terminal Window:

$ sudo npm install -g api2swagger-ext

input file structure

{
  "apiInfo": {    
    "host": "",
    "basePath": "",
    "schemes": [""],
    "consumes": [""],
    "produces": [""],
    "info": {
      "description": "",
      "title": "",
      "version": "",
      "termsOfService": "",
      "contact": {
        "email": ""
      }
    },
    "tags": [
      {
        "name": "",
        "description": ""
      }
    ],
    "metadata": {
      "tags": [],
      "description": ""
    }
  },
  "params": {
    "path": [],
    "query": [],
    "header": [],
    "body": {}    
  },
  "endpoint": "",
  "method":"",
  "outputExamples": [],
  "optionalResponse":{}
}

apiInfo

This tag contains the description for the API.

Property	Type	Description
"host"	string	API host
"basePath"	string	API base path
"schemes"	string	API supported schemas
"consumes"	string	API supported consumable types
"produces"	string	API output types

info

Property	Type	Description
"description"	string	API description
"title"	string	API title
"version"	string	API version
"termsOfService"	string	Terms of service text
"contact"	object	Contact info

tags

Array of API global tags

Property	Type	Description
"name"	string	API Tag name
"description"	string	API Tag description

metadata

Info related to a single API endpoint

Property	Type	Description
tags	string []	Array contains the API endpoint tags
description	string	API endpoint description

params

Contains the API endpoint parameters definitions

Property	Type	Description
path	object []	array of parameters that exists in the path
query	object []	array of parameters that exists in the query string
header	object []	array of parameters that exists in the request header
body	object	json object representing the request/response body

path & query

Each object in the list has the following structure

{
  "name": "",
  "description": "",
  "required": true,
  "type": "string"
}

No need to add the locale path parameter as it is already defined in the shared file.

header

Each object in the list has the following structure

{
  "name": "",
  "description": "",
  "type": "string"
}

body

Body parameter will be constructed based on the API execution response; use this property to override the desired parameter; or to specify the request body for put, patch, delete, and post mehods

Remark : You don't have to provide all parameters sections, just add what you need

endpoint

The full URL of the endpoint including all path parameters and replacement tags

method

The HTTP method GET, POST, PUT, DELETE, PATCH...

outputExamples

An array that contains actual calls to a deployed API to exctract the response from. The array could be a string or object array, if we the endpoint doesn't need any parameters outside the URL a string that represnts the desired url is enough, otherwise the object should have the follwoing structure

{
  "url": "",
  "body": {},
  "headers": []
}

Property	Type	Description
url	string	request url
body	oject	dynamic object represending the request body
headers	string []	request headers

Remarks : Make sure that the targeted server is up and running before run the documentation generation

optionalResponse

By default all properties in the response object -for both array and single object- are required, if the response has some optional parameteres the output can be overriden using the optionalResponse property using the following structure

{
  "optionalResponse":{
    "RESPONSE CODE" : ["OPTIONAL PARAMETER NAME",...]
  }
}

Example

{
  "optionalResponse":{
    "200" : ["id","responseId"]
  }
}