api2swagger-ext
Generate Swagger 2.0 (Open API) spec from Curl like API Call.
Last updated 3 years ago by yaser.amin .
MIT · Repository · Bugs · Original npm · Tarball · package.json
$ cnpm install api2swagger-ext 
SYNC missed versions from official npm registry.

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"]
  }
}

Current Tags

  • 0.1.0                                ...           latest (3 years ago)

7 Versions

  • 0.1.0                                ...           3 years ago
  • 0.0.6                                ...           3 years ago
  • 0.0.5                                ...           3 years ago
  • 0.0.4                                ...           3 years ago
  • 0.0.3                                ...           3 years ago
  • 0.0.2                                ...           3 years ago
  • 0.0.1                                ...           3 years ago
Maintainers (1)
Downloads
Today 0
This Week 0
This Month 0
Last Day 0
Last Week 1
Last Month 5
Dependencies (7)
Dev Dependencies (4)
Dependents (0)
None

Copyright 2014 - 2016 © taobao.org |