Hello Everyone,
UPDATE : We now have UI tool hosted online to generate OpenApi Spec (Swagger). Find more about same here.
We now have a new exciting tool related to swagger called api2swagger . We all love swagger, which is now called Open API. It’s a simple yet powerful representation of your RESTful API. It helps you document your APIs and use it during the entire life cycle of working with REST APIs.
It helps you many ways like,
- Generate beautiful docs using Swagger UI
- Generate documentation in Apigee Developer Portal using smartdocs feature
- Test & Monitor your APIs using Apigee Health
- Create API Proxies using swagger2api tool in Apigee Edge
- Generate SDK for various languages using Swagger Code Gen
Many other tools also support swagger 2.0 specifications like postman etc etc…
To do all above, we need to write a swagger specification for our existing / new REST APIs. I am sure many of you agree, writing swagger 2.0 specifications from scratch is so painful. Because, You need to deal with so many lines of code & complex nested structures.
Let’s say, we need to write swagger specifications for few simple API calls like Apigee Developer Edge Management APIs listed here. If you start writing swagger spec for few of these API calls it will come around 1000 lines of code. Think about how much time it will take to fiddle with highly complex JSON structure. Swagger specification for above API calls will look like below code.
{
"swagger": "2.0",
"host": "api.enterprise.apigee.com",
"schemes": [
"https",
"http"
],
"info": {
"description": "Apigee Edge Management Apis Open API 2.0 (Swagger) Spec",
"title": "Apigee Edge APIs",
"version": "0.0.1",
"termsOfService": "http://apigee.com/about/terms",
"contact": {
"name": "Apigee Docs",
"url": "http://apigee.com/about/apigee#block-bean-about-apigee-contact-us-header",
"email": "docs@apigee.com"
},
"license": {
"name": "Apache 2.0",
"url": "http://apigee.com"
}
},
"basePath": "/v1",
"paths": {
"/organizations/{organization}/developers": {
"post": {
"description": "Create Developer",
"summary": "Creates a profile for a developer in an organization. Once created, the developer can register an app and receive an API key.",
"externalDocs": {
"description": "Find out more",
"url": "http://docs.apigee.com/management/apis/post/organizations/%7Borg_name%7D/developers"
},
"operationId": "createDeveloper",
"tags": [
"developers"
],
"produces": [
"application/json"
],
"responses": {
"201": {
"description": "Created",
"schema": {
"description": "",
"type": "object",
"properties": {
"apps": {
"type": "array",
"items": {
"properties": {
}
}
},
"email": {
"type": "string",
"minLength": 1
},
"developerId": {
"type": "string",
"minLength": 1
},
"firstName": {
"type": "string",
"minLength": 1
},
"lastName": {
"type": "string",
"minLength": 1
},
"userName": {
"type": "string",
"minLength": 1
},
"organizationName": {
"type": "string",
"minLength": 1
},
"status": {
"type": "string",
"minLength": 1
},
"attributes": {
"type": "array",
"uniqueItems": true,
"minItems": 1,
"items": {
"required": [
"name",
"value"
],
"properties": {
"name": {
"type": "string",
"minLength": 1
},
"value": {
"type": "string",
"minLength": 1
}
}
}
},
"createdAt": {
"type": "number"
},
"createdBy": {
"type": "string",
"minLength": 1
},
"lastModifiedAt": {
"type": "number"
},
"lastModifiedBy": {
"type": "string",
"minLength": 1
}
},
"required": [
"apps",
"email",
"developerId",
"firstName",
"lastName",
"userName",
"organizationName",
"status",
"attributes",
"createdAt",
"createdBy",
"lastModifiedAt",
"lastModifiedBy"
]
}
}
},
"security": [
{
"basicAuth": [
]
}
],
"parameters": [
{
"in": "header",
"name": "Content-Type",
"description": "Request Content Type",
"required": true,
"type": "string",
"enum": [
"application/json"
]
},
{
"in": "body",
"name": "body",
"description": "Request Payload",
"required": true,
"schema": {
"description": "",
"type": "object",
"properties": {
"email": {
"type": "string",
"minLength": 1
},
"firstName": {
"type": "string",
"minLength": 1
},
"lastName": {
"type": "string",
"minLength": 1
},
"userName": {
"type": "string",
"minLength": 1
},
"attributes": {
"type": "array",
"uniqueItems": true,
"minItems": 1,
"items": {
"required": [
"name",
"value"
],
"properties": {
"name": {
"type": "string",
"minLength": 1
},
"value": {
"type": "string",
"minLength": 1
}
}
}
}
},
"required": [
"email",
"firstName",
"lastName",
"userName",
"attributes"
]
}
},
{
"in": "path",
"name": "organization",
"description": "Apigee Edge Org Name",
"required": true,
"type": "string"
}
]
},
"get": {
"description": "List Developers",
"summary": "List all Developers in an Organization",
"externalDocs": {
"description": "Find out more",
"url": "http://docs.apigee.com/management/apis/get/organizations/%7Borg_name%7D/developers"
},
"operationId": "listDevelopers",
"tags": [
"developers"
],
"produces": [
"application/json"
],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "array",
"description": "",
"minItems": 1,
"uniqueItems": true,
"items": {
"type": "object",
"properties": {
}
}
}
}
},
"security": [
{
"basicAuth": [
]
}
],
"parameters": [
{
"in": "path",
"name": "organization",
"description": "Apigee Edge Org Name",
"required": true,
"type": "string"
}
]
}
},
"/organizations/{organization}/developers/{developerEmail}": {
"delete": {
"description": "Delete Developer",
"summary": "Deletes a developer from an organization. All apps associated with the developer are also removed from the organization.",
"externalDocs": {
"description": "Find out more",
"url": "http://docs.apigee.com/management/apis/delete/organizations/%7Borg_name%7D/developers/%7Bdeveloper_email_or_id%7D"
},
"operationId": "deleteDeveloper",
"tags": [
"developers"
],
"produces": [
"application/json"
],
"responses": {
"200": {
"description": "OK",
"schema": {
"description": "",
"type": "object",
"properties": {
"apps": {
"type": "array",
"items": {
"properties": {
}
}
},
"email": {
"type": "string",
"minLength": 1
},
"developerId": {
"type": "string",
"minLength": 1
},
"firstName": {
"type": "string",
"minLength": 1
},
"lastName": {
"type": "string",
"minLength": 1
},
"userName": {
"type": "string",
"minLength": 1
},
"organizationName": {
"type": "string",
"minLength": 1
},
"status": {
"type": "string",
"minLength": 1
},
"attributes": {
"type": "array",
"items": {
"properties": {
}
}
},
"createdAt": {
"type": "number"
},
"createdBy": {
"type": "string",
"minLength": 1
},
"lastModifiedAt": {
"type": "number"
},
"lastModifiedBy": {
"type": "string",
"minLength": 1
}
},
"required": [
"apps",
"email",
"developerId",
"firstName",
"lastName",
"userName",
"organizationName",
"status",
"attributes",
"createdAt",
"createdBy",
"lastModifiedAt",
"lastModifiedBy"
]
}
}
},
"security": [
{
"basicAuth": [
]
}
],
"parameters": [
{
"in": "path",
"name": "organization",
"description": "Apigee Edge Org Name",
"required": true,
"type": "string"
},
{
"in": "path",
"name": "developerEmail",
"description": "Developer Email Address",
"required": true,
"type": "string"
}
]
},
"get": {
"description": "Get Developers",
"summary": "Returns the profile for a developer by email address or ID. All time values are UNIX time values. The profile includes the developer's email address, ID, name, and other information.",
"externalDocs": {
"description": "Find out more",
"url": "http://docs.apigee.com/management/apis/get/organizations/%7Borg_name%7D/developers/%7Bdeveloper_email_or_id%7D"
},
"operationId": "getDeveloper",
"tags": [
"developers"
],
"produces": [
"application/json"
],
"responses": {
"200": {
"description": "OK",
"schema": {
"description": "",
"type": "object",
"properties": {
"apps": {
"type": "array",
"items": {
"properties": {
}
}
},
"companies": {
"type": "array",
"items": {
"properties": {
}
}
},
"email": {
"type": "string",
"minLength": 1
},
"developerId": {
"type": "string",
"minLength": 1
},
"firstName": {
"type": "string",
"minLength": 1
},
"lastName": {
"type": "string",
"minLength": 1
},
"userName": {
"type": "string",
"minLength": 1
},
"organizationName": {
"type": "string",
"minLength": 1
},
"status": {
"type": "string",
"minLength": 1
},
"attributes": {
"type": "array",
"items": {
"properties": {
}
}
},
"createdAt": {
"type": "number"
},
"createdBy": {
"type": "string",
"minLength": 1
},
"lastModifiedAt": {
"type": "number"
},
"lastModifiedBy": {
"type": "string",
"minLength": 1
}
},
"required": [
"apps",
"companies",
"email",
"developerId",
"firstName",
"lastName",
"userName",
"organizationName",
"status",
"attributes",
"createdAt",
"createdBy",
"lastModifiedAt",
"lastModifiedBy"
]
}
}
},
"security": [
{
"basicAuth": [
]
}
],
"parameters": [
{
"in": "path",
"name": "organization",
"description": "Apigee Edge Org Name",
"required": true,
"type": "string"
},
{
"in": "path",
"name": "developerEmail",
"description": "Developer Email Address",
"required": true,
"type": "string"
}
]
},
"put": {
"description": "Update Developer",
"summary": "Update an existing developer profile.",
"externalDocs": {
"description": "Find out more",
"url": "http://docs.apigee.com/management/apis/put/organizations/%7Borg_name%7D/developers/%7Bdeveloper_email_or_id%7D"
},
"operationId": "updateDeveloper",
"tags": [
"developers"
],
"produces": [
"application/json"
],
"responses": {
"200": {
"description": "OK",
"schema": {
"description": "",
"type": "object",
"properties": {
"apps": {
"type": "array",
"items": {
"properties": {
}
}
},
"companies": {
"type": "array",
"items": {
"properties": {
}
}
},
"email": {
"type": "string",
"minLength": 1
},
"developerId": {
"type": "string",
"minLength": 1
},
"firstName": {
"type": "string",
"minLength": 1
},
"lastName": {
"type": "string",
"minLength": 1
},
"userName": {
"type": "string",
"minLength": 1
},
"organizationName": {
"type": "string",
"minLength": 1
},
"status": {
"type": "string",
"minLength": 1
},
"attributes": {
"type": "array",
"uniqueItems": true,
"minItems": 1,
"items": {
"required": [
"name",
"value"
],
"properties": {
"name": {
"type": "string",
"minLength": 1
},
"value": {
"type": "string",
"minLength": 1
}
}
}
},
"createdAt": {
"type": "number"
},
"createdBy": {
"type": "string",
"minLength": 1
},
"lastModifiedAt": {
"type": "number"
},
"lastModifiedBy": {
"type": "string",
"minLength": 1
}
},
"required": [
"apps",
"companies",
"email",
"developerId",
"firstName",
"lastName",
"userName",
"organizationName",
"status",
"attributes",
"createdAt",
"createdBy",
"lastModifiedAt",
"lastModifiedBy"
]
}
}
},
"security": [
{
"basicAuth": [
]
}
],
"parameters": [
{
"in": "header",
"name": "Content-Type",
"description": "Request Content Type",
"required": true,
"type": "string",
"enum": [
"application/json"
]
},
{
"in": "body",
"name": "body",
"description": "Request Payload",
"required": true,
"schema": {
"description": "",
"type": "object",
"properties": {
"email": {
"type": "string",
"minLength": 1
},
"firstName": {
"type": "string",
"minLength": 1
},
"lastName": {
"type": "string",
"minLength": 1
},
"userName": {
"type": "string",
"minLength": 1
},
"attributes": {
"type": "array",
"uniqueItems": true,
"minItems": 1,
"items": {
"required": [
"name",
"value"
],
"properties": {
"name": {
"type": "string",
"minLength": 1
},
"value": {
"type": "string",
"minLength": 1
}
}
}
}
},
"required": [
"email",
"firstName",
"lastName",
"userName",
"attributes"
]
}
},
{
"in": "path",
"name": "organization",
"description": "Apigee Edge Org Name",
"required": true,
"type": "string"
},
{
"in": "path",
"name": "developerEmail",
"description": "Developer Email Address",
"required": true,
"type": "string"
}
]
},
"post": {
"description": "Set Developer Status",
"summary": "Sets a developer's status to active, inactive, or login_lock.",
"externalDocs": {
"description": "Find out more",
"url": "http://docs.apigee.com/management/apis/post/organizations/%7Borg_name%7D/developers/%7Bdeveloper_email_or_id%7D"
},
"operationId": "setDeveloperStatus",
"tags": [
"developers"
],
"produces": [
"*/*"
],
"responses": {
"204": {
"description": "No Content"
}
},
"security": [
{
"basicAuth": [
]
}
],
"parameters": [
{
"in": "query",
"name": "action",
"description": "Set to active, inactive, or login_lock.",
"type": "string",
"required": true,
"enum": [
"inactive",
"active",
"login_block"
]
},
{
"in": "header",
"name": "Content-Type",
"description": "Request Content Type",
"required": true,
"type": "string",
"enum": [
"application/octet-stream"
]
},
{
"in": "path",
"name": "organization",
"description": "Apigee Edge Org Name",
"required": true,
"type": "string"
},
{
"in": "path",
"name": "developerEmail",
"description": "Developer Email Address",
"required": true,
"type": "string"
}
]
}
},
"/organizations/{org}/developers/{developerEmail}": {
"get": {
"description": "Get Developer By App",
"summary": "Gets the developer profile by app name. The profile retrieved is for the developer associated with the app in the organization. ",
"externalDocs": {
"description": "Find out more",
"url": "http://docs.apigee.com/management/apis/get/organizations/%7Borg_name%7D/developers-0"
},
"operationId": "getDeveloperByApp",
"tags": [
"developers"
],
"produces": [
"application/json"
],
"responses": {
"200": {
"description": "OK",
"schema": {
"description": "",
"type": "object",
"properties": {
"apps": {
"type": "array",
"items": {
"properties": {
}
}
},
"companies": {
"type": "array",
"items": {
"properties": {
}
}
},
"email": {
"type": "string",
"minLength": 1
},
"developerId": {
"type": "string",
"minLength": 1
},
"firstName": {
"type": "string",
"minLength": 1
},
"lastName": {
"type": "string",
"minLength": 1
},
"userName": {
"type": "string",
"minLength": 1
},
"organizationName": {
"type": "string",
"minLength": 1
},
"status": {
"type": "string",
"minLength": 1
},
"attributes": {
"type": "array",
"items": {
"properties": {
}
}
},
"createdAt": {
"type": "number"
},
"createdBy": {
"type": "string",
"minLength": 1
},
"lastModifiedAt": {
"type": "number"
},
"lastModifiedBy": {
"type": "string",
"minLength": 1
}
},
"required": [
"apps",
"companies",
"email",
"developerId",
"firstName",
"lastName",
"userName",
"organizationName",
"status",
"attributes",
"createdAt",
"createdBy",
"lastModifiedAt",
"lastModifiedBy"
]
}
}
},
"security": [
{
"basicAuth": [
]
}
],
"parameters": [
{
"in": "query",
"name": "app",
"description": "Developer App Name",
"type": "string",
"required": true,
"enum": [
"appName"
]
},
{
"in": "path",
"name": "org",
"description": "Apigee Edge Org Name",
"required": true,
"type": "string"
},
{
"in": "path",
"name": "developerEmail",
"description": "Developer Email Address",
"required": true,
"type": "string"
}
]
}
}
},
"securityDefinitions": {
"basicAuth": {
"type": "basic",
"description": "HTTP Basic Authentication. Works over `HTTP` and `HTTPS`"
}
}
}
I am sure, you might have taken few seconds to scroll down above code. Think about writing this code & maintaining it 
What if I tell you above code is auto generated using a tool within few minutes using simple CURL like syntax ? I am sure it’s going to save a lot of time, change the way you document your APIs & manage your APIs. Above Swagger spec is generated using API2Swagger Node.js based command line tool.
Installation
Installing api2swagger is as simple as any other node module from NPM. Requirements to use this tool are Node.JS and NPM. You can install this tool by running the following command after you have Node.JS and NPM installed on your local machine.
$ sudo npm install -g api2swagger
Once you have api2swagger installed, you are ready to generate a Swagger 2.0 spec from CURL like commands.
How to use api2swagger
Api2swagger supports GET, POST, PUT, DELETE methods and you just need to make a CURL like api call and answer some questions. Api2swagger supports incremental update of swagger spec for same basepath.
Let’s generate swagger 2.0 spec for Google Books API to understand how Api2Swagger works. We are going to generate swagger 2.0 spec for below mentioned API calls.
GET https://www.googleapis.com/books/v1/volumes?q=quilting
GET https://www.googleapis.com/books/v1/volumes/{VOLUMEID}
api2swagger command line options are similar to CURL command line tool. Let’s make the first API call & generate swagger 2.0 spec for Google Books API.
$ api2swagger -e "https://www.googleapis.com/books/v1/volumes?q=quilting" -o /Users/Anil/Desktop/googleBooks.json -X GET
-e : (EndPoint) : It’s used to specify end point. It also support username, password basic authentication sent in URI. Like https://username:password@example.com
-X : (HTTP Method) : GET, POST, PUT , DELETE supported
-o : (Output) : Location of new swagger json file yet to be created / existing swagger spec to update new method / resource.
-d : (data) : Payload , Form Data used in POST, PUT, DELETE
-H : (Headers) : Request headers
Once you run above command, it asks for few details like Title of swagger spec, Contact Information etc..
Then you will be asked for details regarding your rest API like, Does your API supports http / https , base path of your API.
Options for basePath will be automatically populated from your API call. After that, you will be asked for details of the API Method,
After collecting few more details, An API call is made to fetch runtime information like request response.
If everything goes as planned, you will see below message,
Swagger JSON File successfully generated in : /Users/Anil/Desktop/googleBooks.json
Let’s open up googleBooks.json and see the content, it should look like below.
{
"swagger": "2.0",
"host": "www.googleapis.com",
"schemes": [
"https",
"http"
],
"info": {
"description": "Swagger 2.0 Specification for Google Books API",
"title": "Google Books API",
"version": "0.0.1",
"termsOfService": "http://example.com/about/terms",
"contact": {
"name": "API Docs",
"url": "http://example.com/contact",
"email": "apidocs@example.com"
},
"license": {
"name": "Apache 2.0",
"url": "http://example.com"
}
},
"basePath": "/books/v1",
"paths": {
"/volumes": {
"get": {
"description": "Book Volumes API",
"summary": "Search for book volumes using search string",
"externalDocs": {
"description": "Find out more",
"url": "https://developers.google.com/books/docs/v1/getting_started"
},
"operationId": "searchVolumes",
"tags": [
"google",
" books"
],
"produces": [
"application/json; charset=UTF-8"
],
"responses": {
"200": {
"description": "OK",
"schema": {
"description": "",
"type": "object",
"properties": {
"kind": {
"type": "string",
"minLength": 1
},
"totalItems": {
"type": "number"
},
"items": {
"type": "array",
"uniqueItems": true,
"minItems": 1,
"items": {
"required": [
"kind",
"id",
"etag",
"selfLink"
],
"properties": {
"kind": {
"type": "string",
"minLength": 1
},
"id": {
"type": "string",
"minLength": 1
},
"etag": {
"type": "string",
"minLength": 1
},
"selfLink": {
"type": "string",
"minLength": 1
},
"volumeInfo": {
"type": "object",
"properties": {
"title": {
"type": "string",
"minLength": 1
},
"subtitle": {
"type": "string",
"minLength": 1
},
"authors": {
"type": "array",
"items": {
"properties": {}
}
},
"publisher": {
"type": "string",
"minLength": 1
},
"publishedDate": {
"type": "string",
"minLength": 1
},
"description": {
"type": "string",
"minLength": 1
},
"industryIdentifiers": {
"type": "array",
"uniqueItems": true,
"minItems": 1,
"items": {
"required": [
"type",
"identifier"
],
"properties": {
"type": {
"type": "string",
"minLength": 1
},
"identifier": {
"type": "string",
"minLength": 1
}
}
}
},
"readingModes": {
"type": "object",
"properties": {
"text": {
"type": "boolean"
},
"image": {
"type": "boolean"
}
},
"required": [
"text",
"image"
]
},
"pageCount": {
"type": "number"
},
"printType": {
"type": "string",
"minLength": 1
},
"categories": {
"type": "array",
"items": {
"properties": {}
}
},
"averageRating": {
"type": "number"
},
"ratingsCount": {
"type": "number"
},
"maturityRating": {
"type": "string",
"minLength": 1
},
"allowAnonLogging": {
"type": "boolean"
},
"contentVersion": {
"type": "string",
"minLength": 1
},
"imageLinks": {
"type": "object",
"properties": {
"smallThumbnail": {
"type": "string",
"minLength": 1
},
"thumbnail": {
"type": "string",
"minLength": 1
}
},
"required": [
"smallThumbnail",
"thumbnail"
]
},
"language": {
"type": "string",
"minLength": 1
},
"previewLink": {
"type": "string",
"minLength": 1
},
"infoLink": {
"type": "string",
"minLength": 1
},
"canonicalVolumeLink": {
"type": "string",
"minLength": 1
}
},
"required": [
"title",
"subtitle",
"authors",
"publisher",
"publishedDate",
"description",
"industryIdentifiers",
"readingModes",
"pageCount",
"printType",
"categories",
"averageRating",
"ratingsCount",
"maturityRating",
"allowAnonLogging",
"contentVersion",
"imageLinks",
"language",
"previewLink",
"infoLink",
"canonicalVolumeLink"
]
},
"saleInfo": {
"type": "object",
"properties": {
"country": {
"type": "string",
"minLength": 1
},
"saleability": {
"type": "string",
"minLength": 1
},
"isEbook": {
"type": "boolean"
}
},
"required": [
"country",
"saleability",
"isEbook"
]
},
"accessInfo": {
"type": "object",
"properties": {
"country": {
"type": "string",
"minLength": 1
},
"viewability": {
"type": "string",
"minLength": 1
},
"embeddable": {
"type": "boolean"
},
"publicDomain": {
"type": "boolean"
},
"textToSpeechPermission": {
"type": "string",
"minLength": 1
},
"epub": {
"type": "object",
"properties": {
"isAvailable": {
"type": "boolean"
}
},
"required": [
"isAvailable"
]
},
"pdf": {
"type": "object",
"properties": {
"isAvailable": {
"type": "boolean"
}
},
"required": [
"isAvailable"
]
},
"webReaderLink": {
"type": "string",
"minLength": 1
},
"accessViewStatus": {
"type": "string",
"minLength": 1
},
"quoteSharingAllowed": {
"type": "boolean"
}
},
"required": [
"country",
"viewability",
"embeddable",
"publicDomain",
"textToSpeechPermission",
"epub",
"pdf",
"webReaderLink",
"accessViewStatus",
"quoteSharingAllowed"
]
},
"searchInfo": {
"type": "object",
"properties": {
"textSnippet": {
"type": "string",
"minLength": 1
}
},
"required": [
"textSnippet"
]
}
}
}
}
},
"required": [
"kind",
"totalItems",
"items"
]
}
}
},
"security": [],
"parameters": [
{
"in": "query",
"name": "q",
"description": "Query String",
"type": "string",
"required": true,
"enum": [
"quilting"
]
}
]
}
}
}
}
You got a swagger spec for google books API. Let’s copy this to apistudio.io to see generated swagger in action.
Generated swagger is working like a charm & you got the documentation for Google Books API.
Let’s add more paths / api methods to our google docs swagger 2.0 spec.
$ api2swagger -e "https://www.googleapis.com/books/v1/volumes/s1gVAAAAYAAJ" -o /Users/Anil/Desktop/googleBooks.json -X GET
This time, since base path and hostname matches you don’t need to enter high level info. Only method related information need to be provided.
Provide more details regarding url parameter,
That’s it, new API path will be appended to existing swagger,
{
"swagger": "2.0",
"host": "www.googleapis.com",
"schemes": [
"https",
"http"
],
"info": {
"description": "Swagger 2.0 Specification for Google Books API",
"title": "Google Books API",
"version": "0.0.1",
"termsOfService": "http://example.com/about/terms",
"contact": {
"name": "API Docs",
"url": "http://example.com/contact",
"email": "apidocs@example.com"
},
"license": {
"name": "Apache 2.0",
"url": "http://example.com"
}
},
"basePath": "/books/v1",
"paths": {
"/volumes": {
"get": {
"description": "Book Volumes API",
"summary": "Search for book volumes using search string",
"externalDocs": {
"description": "Find out more",
"url": "https://developers.google.com/books/docs/v1/getting_started"
},
"operationId": "searchVolumes",
"tags": [
"google",
" books"
],
"produces": [
"application/json; charset=UTF-8"
],
"responses": {
"200": {
"description": "OK",
"schema": {
"description": "",
"type": "object",
"properties": {
"kind": {
"type": "string",
"minLength": 1
},
"totalItems": {
"type": "number"
},
"items": {
"type": "array",
"uniqueItems": true,
"minItems": 1,
"items": {
"required": [
"kind",
"id",
"etag",
"selfLink"
],
"properties": {
"kind": {
"type": "string",
"minLength": 1
},
"id": {
"type": "string",
"minLength": 1
},
"etag": {
"type": "string",
"minLength": 1
},
"selfLink": {
"type": "string",
"minLength": 1
},
"volumeInfo": {
"type": "object",
"properties": {
"title": {
"type": "string",
"minLength": 1
},
"subtitle": {
"type": "string",
"minLength": 1
},
"authors": {
"type": "array",
"items": {
"properties": {}
}
},
"publisher": {
"type": "string",
"minLength": 1
},
"publishedDate": {
"type": "string",
"minLength": 1
},
"description": {
"type": "string",
"minLength": 1
},
"industryIdentifiers": {
"type": "array",
"uniqueItems": true,
"minItems": 1,
"items": {
"required": [
"type",
"identifier"
],
"properties": {
"type": {
"type": "string",
"minLength": 1
},
"identifier": {
"type": "string",
"minLength": 1
}
}
}
},
"readingModes": {
"type": "object",
"properties": {
"text": {
"type": "boolean"
},
"image": {
"type": "boolean"
}
},
"required": [
"text",
"image"
]
},
"pageCount": {
"type": "number"
},
"printType": {
"type": "string",
"minLength": 1
},
"categories": {
"type": "array",
"items": {
"properties": {}
}
},
"averageRating": {
"type": "number"
},
"ratingsCount": {
"type": "number"
},
"maturityRating": {
"type": "string",
"minLength": 1
},
"allowAnonLogging": {
"type": "boolean"
},
"contentVersion": {
"type": "string",
"minLength": 1
},
"imageLinks": {
"type": "object",
"properties": {
"smallThumbnail": {
"type": "string",
"minLength": 1
},
"thumbnail": {
"type": "string",
"minLength": 1
}
},
"required": [
"smallThumbnail",
"thumbnail"
]
},
"language": {
"type": "string",
"minLength": 1
},
"previewLink": {
"type": "string",
"minLength": 1
},
"infoLink": {
"type": "string",
"minLength": 1
},
"canonicalVolumeLink": {
"type": "string",
"minLength": 1
}
},
"required": [
"title",
"subtitle",
"authors",
"publisher",
"publishedDate",
"description",
"industryIdentifiers",
"readingModes",
"pageCount",
"printType",
"categories",
"averageRating",
"ratingsCount",
"maturityRating",
"allowAnonLogging",
"contentVersion",
"imageLinks",
"language",
"previewLink",
"infoLink",
"canonicalVolumeLink"
]
},
"saleInfo": {
"type": "object",
"properties": {
"country": {
"type": "string",
"minLength": 1
},
"saleability": {
"type": "string",
"minLength": 1
},
"isEbook": {
"type": "boolean"
}
},
"required": [
"country",
"saleability",
"isEbook"
]
},
"accessInfo": {
"type": "object",
"properties": {
"country": {
"type": "string",
"minLength": 1
},
"viewability": {
"type": "string",
"minLength": 1
},
"embeddable": {
"type": "boolean"
},
"publicDomain": {
"type": "boolean"
},
"textToSpeechPermission": {
"type": "string",
"minLength": 1
},
"epub": {
"type": "object",
"properties": {
"isAvailable": {
"type": "boolean"
}
},
"required": [
"isAvailable"
]
},
"pdf": {
"type": "object",
"properties": {
"isAvailable": {
"type": "boolean"
}
},
"required": [
"isAvailable"
]
},
"webReaderLink": {
"type": "string",
"minLength": 1
},
"accessViewStatus": {
"type": "string",
"minLength": 1
},
"quoteSharingAllowed": {
"type": "boolean"
}
},
"required": [
"country",
"viewability",
"embeddable",
"publicDomain",
"textToSpeechPermission",
"epub",
"pdf",
"webReaderLink",
"accessViewStatus",
"quoteSharingAllowed"
]
},
"searchInfo": {
"type": "object",
"properties": {
"textSnippet": {
"type": "string",
"minLength": 1
}
},
"required": [
"textSnippet"
]
}
}
}
}
},
"required": [
"kind",
"totalItems",
"items"
]
}
}
},
"security": [],
"parameters": [
{
"in": "query",
"name": "q",
"description": "Query String",
"type": "string",
"required": true,
"enum": [
"quilting"
]
}
]
}
},
"/volumes/{volumeId}": {
"get": {
"description": "Volume Info",
"summary": "Get Book Volume Details",
"externalDocs": {
"description": "Find out more",
"url": "http://docs.example.com/management/apis/get/entities"
},
"operationId": "getVolumeInfo",
"tags": [
"google",
" books"
],
"produces": [
"application/json; charset=UTF-8"
],
"responses": {
"200": {
"description": "OK",
"schema": {
"description": "",
"type": "object",
"properties": {
"kind": {
"type": "string",
"minLength": 1
},
"id": {
"type": "string",
"minLength": 1
},
"etag": {
"type": "string",
"minLength": 1
},
"selfLink": {
"type": "string",
"minLength": 1
},
"volumeInfo": {
"type": "object",
"properties": {
"title": {
"type": "string",
"minLength": 1
},
"authors": {
"type": "array",
"items": {
"properties": {}
}
},
"publisher": {
"type": "string",
"minLength": 1
},
"publishedDate": {
"type": "string",
"minLength": 1
},
"description": {
"type": "string",
"minLength": 1
},
"readingModes": {
"type": "object",
"properties": {
"text": {
"type": "boolean"
},
"image": {
"type": "boolean"
}
},
"required": [
"text",
"image"
]
},
"pageCount": {
"type": "number"
},
"printedPageCount": {
"type": "number"
},
"dimensions": {
"type": "object",
"properties": {
"height": {
"type": "string",
"minLength": 1
}
},
"required": [
"height"
]
},
"printType": {
"type": "string",
"minLength": 1
},
"averageRating": {
"type": "number"
},
"ratingsCount": {
"type": "number"
},
"maturityRating": {
"type": "string",
"minLength": 1
},
"allowAnonLogging": {
"type": "boolean"
},
"contentVersion": {
"type": "string",
"minLength": 1
},
"imageLinks": {
"type": "object",
"properties": {
"smallThumbnail": {
"type": "string",
"minLength": 1
},
"thumbnail": {
"type": "string",
"minLength": 1
}
},
"required": [
"smallThumbnail",
"thumbnail"
]
},
"language": {
"type": "string",
"minLength": 1
},
"previewLink": {
"type": "string",
"minLength": 1
},
"infoLink": {
"type": "string",
"minLength": 1
},
"canonicalVolumeLink": {
"type": "string",
"minLength": 1
}
},
"required": [
"title",
"authors",
"publisher",
"publishedDate",
"description",
"readingModes",
"pageCount",
"printedPageCount",
"dimensions",
"printType",
"averageRating",
"ratingsCount",
"maturityRating",
"allowAnonLogging",
"contentVersion",
"imageLinks",
"language",
"previewLink",
"infoLink",
"canonicalVolumeLink"
]
},
"layerInfo": {
"type": "object",
"properties": {
"layers": {
"type": "array",
"uniqueItems": true,
"minItems": 1,
"items": {
"required": [
"layerId",
"volumeAnnotationsVersion"
],
"properties": {
"layerId": {
"type": "string",
"minLength": 1
},
"volumeAnnotationsVersion": {
"type": "string",
"minLength": 1
}
}
}
}
},
"required": [
"layers"
]
},
"saleInfo": {
"type": "object",
"properties": {
"country": {
"type": "string",
"minLength": 1
},
"saleability": {
"type": "string",
"minLength": 1
},
"isEbook": {
"type": "boolean"
}
},
"required": [
"country",
"saleability",
"isEbook"
]
},
"accessInfo": {
"type": "object",
"properties": {
"country": {
"type": "string",
"minLength": 1
},
"viewability": {
"type": "string",
"minLength": 1
},
"embeddable": {
"type": "boolean"
},
"publicDomain": {
"type": "boolean"
},
"textToSpeechPermission": {
"type": "string",
"minLength": 1
},
"epub": {
"type": "object",
"properties": {
"isAvailable": {
"type": "boolean"
}
},
"required": [
"isAvailable"
]
},
"pdf": {
"type": "object",
"properties": {
"isAvailable": {
"type": "boolean"
}
},
"required": [
"isAvailable"
]
},
"webReaderLink": {
"type": "string",
"minLength": 1
},
"accessViewStatus": {
"type": "string",
"minLength": 1
},
"quoteSharingAllowed": {
"type": "boolean"
}
},
"required": [
"country",
"viewability",
"embeddable",
"publicDomain",
"textToSpeechPermission",
"epub",
"pdf",
"webReaderLink",
"accessViewStatus",
"quoteSharingAllowed"
]
}
},
"required": [
"kind",
"id",
"etag",
"selfLink",
"volumeInfo",
"layerInfo",
"saleInfo",
"accessInfo"
]
}
}
},
"security": [],
"parameters": [
{
"in": "path",
"name": "volumeId",
"description": "Volume Id",
"required": true,
"type": "string"
}
]
}
}
}
}
API2Swagger currently support only JSON / plain text based request / response. As of today, API2Swagger doesn’t support all use cases. I can say 70 - 80 % use cases are covered.
Stay tuned, we will be using this tool to generate swagger 2.0 spec for Management APIs which in turn helps to generate SDKs for Apigee Management APIs. Please keep us posted & share your feedback.
Important :
Api2swagger 0.1.2 release is an alpha release. Please feel free to log issues / comments / improvement request in github here. I am also looking for co-maintainer for this project. Please contact me if anyone interested using comments section.
Thank you very much for your valuable feedback. Agree, Complex objects should be moved into definitions section & reference using $ref. Looking forward to your PR. Keep us posted.