Hello Everyone,
We have a new tool that will help you connect a missing piece in the Apigee developer ecosystem. I am sure many of you love SmartDocs in the Apigee Developer Portal. SmartDocs, which allow you to create documentation for your APIs using a beautiful Swagger-like UI, are generated from either a WADL or a OpenAPI 2.0 specification. One thing that was missing, though, was out-of-the-box support for generating SmartDocs directly from your Apigee Edge API proxies.
The apigee2openapi tool will help you bridge that gap to some extent. In this article, Iâll describe apigee2openapi and show you how to use it.
apigee2openapi
apigee2openapi is a Node.JS command line tool that will help you convert an Apigee API proxy to a Swagger 2.0 spec that can be used to generate SmartDocs. (It does the opposite of what the swagger2api tool does: lets you generate Apigee API proxies from openapi 2.0 specs.)
Installation
Installing apigee2openapi 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 apigee2openapi
Once you have apigee2openapi installed, you are ready to generate a OpenAPI 2.0 spec from API proxies. In this article, Iâll use the popular Swagger 2.0 Petstore API to first create an API proxy, then generate a OpenAPI 2.0 spec from that proxy.
Hereâs what apigee2openapi does:
- Queries for Apigee Edge API proxy details.
- Downloads the API proxy bundle.
- Unzips the bundle and reads the API proxy XML files.
- Generates OpenAPI JSON files. (It currently supports only JSON. You can generate YAML from JSON using API Studio as described later in this article.)
- apigee2openapi supports multiple proxy endpoints.
How to use apigee2openapi (Earlier called Apigee2Swagger)
First, create an Apigee API proxy that will later be converted to a OpenAPI 2.0 spec.
Create the API proxy
Attached to this article is the petStore sample API proxy that you can import into your own Apigee Edge environment. The following image shows this being done in the Edge management UI. (The process is described here in the Apigee documentation.)
You can also generate the API proxy from a OpenAPI 2.0 spec using the swagger2api tool using the following command.
$ swagger2api generateApi petStore -s <a href="http://petstore.swagger.io/v2/swagger.json">http://petstore.swagger.io/v2/swagger.json</a> -D -d /Users/Anil/Desktop/
Your petStore API proxy should look like the following once you have successfully imported it into your Edge environment.
Generate the OpenAPI spec
Now generate the OpenAPI 2.0 spec from the API Proxy using apigee2openapi
Run the following command in a terminal. Change the the path in option -d to the destination directory on your local machine where you want to download the API proxy and generated Swagger files.
$ apigee2openapi -d /Users/Anil/Documents
When you run the command, youâll be prompted for the following:
- Base URI ? https://api.enterprise.apigee.com
- Org Name ? [your Edge organization name]
- User ID ? [your Edge organization administrator email address]
- Password ? [your Edge organization administrator password]
- API Proxy Name ? [the name of the API proxy. In our case, itâs petStore]
- Revision Number ? [the API proxy revision number]
- API Proxy End Point ? [the API proxy target endpoint URL]
The OpenAPI 2.0 spec is generated from the Apigee API proxy and stored in the local directory specified; for example, /Users/Anil/Documents/petStore/petStore.json. The contents of petStore.json should look like this:
{
"swagger": "2.0",
"info": {
"description": "Swagger Petstore",
"version": "1.0.0",
"title": "petStore",
"contact": {
"email": "asagar.nodeapp@gmail.com"
}
},
"host": "asagarnodeapp-test.apigee.net",
"schemes": [
"https"
],
"basePath": "/petStore",
"paths": {
"/pet": {
"put": {
"operationId": "updatePet",
"summary": "Update an existing pet",
"responses": {
"200": {
"description": "successful operation"
}
}
}
},
"/pet/findByStatus": {
"get": {
"operationId": "findPetsByStatus",
"summary": "Finds Pets by status",
"responses": {
"200": {
"description": "successful operation"
}
}
}
},
"/pet/findByTags": {
"get": {
"operationId": "findPetsByTags",
"summary": "Finds Pets by tags",
"responses": {
"200": {
"description": "successful operation"
}
}
}
},
"/pet/{petId}": {
"delete": {
"operationId": "deletePet",
"summary": "Deletes a pet",
"responses": {
"200": {
"description": "successful operation"
}
},
"parameters": [
{
"name": "petId",
"in": "path",
"required": true,
"type": "string"
}
]
}
},
"/pet/{petId}/uploadImage": {
"post": {
"operationId": "uploadFile",
"summary": "uploads an image",
"responses": {
"200": {
"description": "successful operation"
}
},
"parameters": [
{
"name": "petId",
"in": "path",
"required": true,
"type": "string"
}
]
}
},
"/store/inventory": {
"get": {
"operationId": "getInventory",
"summary": "Returns pet inventories by status",
"responses": {
"200": {
"description": "successful operation"
}
}
}
},
"/store/order": {
"post": {
"operationId": "placeOrder",
"summary": "Place an order for a pet",
"responses": {
"200": {
"description": "successful operation"
}
}
}
},
"/store/order/{orderId}": {
"delete": {
"operationId": "deleteOrder",
"summary": "Delete purchase order by ID",
"responses": {
"200": {
"description": "successful operation"
}
},
"parameters": [
{
"name": "orderId",
"in": "path",
"required": true,
"type": "string"
}
]
}
},
"/user": {
"post": {
"operationId": "createUser",
"summary": "Create user",
"responses": {
"200": {
"description": "successful operation"
}
}
}
},
"/user/createWithArray": {
"post": {
"operationId": "createUsersWithArrayInput",
"summary": "Creates list of users with given input array",
"responses": {
"200": {
"description": "successful operation"
}
}
}
},
"/user/createWithList": {
"post": {
"operationId": "createUsersWithListInput",
"summary": "Creates list of users with given input array",
"responses": {
"200": {
"description": "successful operation"
}
}
}
},
"/user/login": {
"get": {
"operationId": "loginUser",
"summary": "Logs user into the system",
"responses": {
"200": {
"description": "successful operation"
}
}
}
},
"/user/logout": {
"get": {
"operationId": "logoutUser",
"summary": "Logs out current logged in user session",
"responses": {
"200": {
"description": "successful operation"
}
}
}
},
"/user/{username}": {
"delete": {
"operationId": "deleteUser",
"summary": "Delete user",
"responses": {
"200": {
"description": "successful operation"
}
},
"parameters": [
{
"name": "username",
"in": "path",
"required": true,
"type": "string"
}
]
}
}
}
}
Now copy that JSON and use apistudio.io to test the generated OpenAPI 2.0 spec.
Navigate to http://apistudio.io/ and click Get Started to open the editor. In the menu, select File > Paste JSON, paste the JSON into the window (thereâs currently a bug that wonât let you see the pasted text), and click Import. Youâll see the petStore Swagger doc in the right pane.
Thatâs it!
To view the doc in the Swagger UI, select File > View SwaggerUI, then click the Show/Hide link. The doc should look like the following. You can also go here and click Show/Hide to see a sample.
Please keep us posted with your comments / suggestions about apigee2openapi
Cheers,
Anil Sagar
