OpenAPI2Apigee - A Node.js Command Line tool to generate Apigee API Proxies from OpenAPI (Swagger)

[anilsr]

Hello Everyone,

OpenAPI is a simple yet powerful representation of your RESTful API . It helps you represent APIs by model first approach. It's a great tool to document APIs. We at Apigee use OpenAPI for many things like SmartDocs - Documentation in Developer Portal, Apigee-127 where you can build APIs using Node.JS with the model first approach.

Apigee-127 allows you to build APIs using OpenAPI Editor and OpenAPI 2.0 Spec. It also allows you to deploy your APIs into a cloud hosting platforms like Amazon & Apigee. But, at the end they are Node JS Apps running on a server exposing APIs.

Few Customers and Apigee Developers shown interest in our community to use OpenAPI 2.0 spec to generate Apigee Edge API Proxies & flows. This will help a API Proxy developer to quickly get started with building API Proxies & Flows instead of building everything from scratch in Apigee Edge. Officially, Apigee supports creating Api Proxy using below mentioned things as Starting Point.

• Backend Service
• API Bundle
• WSDL
• No Target
• New Node.JS
• Existing Node.JS

API Bundle is Apigee way of specifying API Proxy using XML & Predefined Template Structure. Developers loves coding & API Bundle is the way to code Apigee API Proxy. What's missing in above list is obviously Swagger Spec 2.0. Most probably you will see that as an option very soon in Apigee Edge UI. But, if you would like to do the same today and start creating Apigee API Proxies from a Swagger 2.0 spec then below explained tool is for your rescue.

We built an Open Source tool called OpenAPI2Apigee to help you generate Apigee API Proxies & Flows from OpenAPI 2.0 specification. It's Node.JS based and gives you command line options using which you can easily generate Apigee API Proxies.

Installing openapi2apigee 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 below command once you have Node.JS & NPM installed on your local machine.

sudo npm install -g openapi2apigee

Once you have it installed, you are ready to generate Apigee Api Proxies from OpenAPI 2.0 specification. In this article let's use popular OpenAPI 2.0 Petstore API to generate Apigee API Proxies.

Functionality of openapi2apigee is very simple,

• Reads the source of OpenAPI 2.0 Spec . Tool currently supports both local file & swagger file hosted in the cloud which is accessible via URL.
• openapi2apigee supports both YAML & JSON formats.
• Swagger source is validated for Swagger 2.0 Spec using swagger parser module.
• If the file is valid, it generates a few folders & XML files according to Apigee API Bundle structure. Information like Base Paths, Resources, Target URL, Schemes and other information will be parsed from OpenAPI Spec 2.0 and used to generate XML files inside Apigee API Bundle.
• Finally, API Bundle is zipped using Node.js easy-zip module so that we can deploy to Apigee Edge.
• Thanks to @Scott Ganyo for Apigee Node Tool , which we are using in swagger2api to deploy generated Apigee API Bundle to Apigee Edge.

Now let's create the Apigee API Proxy for Swagger Pet Store example.

• openapi2apigee exposes a command called generateApi .
• First Argument to the command is API Proxy name, in our case it's petStore.
• Options that need to be passed along with command is -s source of swagger , -d destination of Apigee API Bundle, -D to deploy to apigee edge.

$ openapi2apigee generateApi petStore -s http://petstore.swagger.io/v2/swagger.json -d /Users/Anil/Desktop -D

Make sure, you change the path using option -d in above command. Once you run the command , it generates Apigee API bundle in specified destination and inquires for Apigee Edge Details so that tool can deploy same.

If it successful, you will get a message "Deployment to Apigee Successfully completed. " . Let's navigate to Apigee Edge UI & check same.

Voila, You will see petStore API Proxy in your API Proxies listing page. Navigate to perStore API details page & develop tab. You will be surprised to see many flows automatically created from swagger spec.

I am sure, It will take lot of time to create manually all above flows and openapi2apigee is a great help here. Guess what, our API Proxy is also deployed and read to make API calls 🙂

Feel free to contribute , Post your suggestions / issues / queries on Github issue queue of openapi2apigee tool.

Cheers,

Anil Sagar

[#2]

Hi Anil,

This tool will create resources(paths) on APIGEE along with the API proxy that is created.

If the swagger has a some policies like OAUTH or API KEY it will not include a policy for the same in APIGEE correct?

Also if the Swagger has defined some schema for the POST body will it create a schema validation policy in APIGEE?

I see it doesnot but can you please confirm?

[anilsr]

Dear @vijay.muralitharan ,

Swagger2Api supports certain volos extensions & creates policies. Please refer articles here and here .

It supports, OAuth, Cache, Verify API Key, Quota, Spike Arrest volos extensions.

Yes, Validation is not supported as of today. You can create a github issue for same.

Cheers,

Anil Sagar

[#4]

Hi! I've created a docker version and published it on hub.docker.com, https://hub.docker.com/r/murf/apigee-swagger2api/

Hopefully it can simplify the workflow for someone. (I use docker everyday and don't have node installed locally, so a fast tool to do the upload helps)

Cheers!

[anilsr]

Dear @mikael.mellgren , Welcome to Apigee Community 🙂

Awesome, Thank you for contributing & publishing tool in docker.

[anilsr]

Update same in readme & pushed new version to npm, link here

[#7]

Wow, this is awesome!!!

Created my application in App Services, created the Swagger and tested, then Swagger2API to deploy to Apigee Edge and I have a working API Proxy in Edge with documentation.

Not only no coding, not even any typing in Apigee Edge 🙂

Great job!!!

[anilsr]

@Kurt Kanaskie , Thank you for great feedback 🙂

[anilsr]

@Kurt Kanaskie , Just FYI, We also support Swagger Spec 2.0 in API Health. You can use swagger 2.0 spec to test your APIs & Monitor your API Health using Apigee Health product. Keep us posted with your valuable feedback. Thank you 🙂

[#10]

Great tool. One issue that I have not been able to resolve - are $ref to external files supported? It could be the underlying swagger parser (haven't yet dug in)

In the specs I have

	       responses:
                    "200": 
	            description: successful operation 
	            schema: 
	                 # shared schema
	                 $ref : "./domain/party.yaml"

Using the Swagger2api on this leads to an error

[SyntaxError: Error in Swagger definition SyntaxError: Data does not match any schemas from "oneOf" Data path: "/paths/~1quote~1{id}/get/responses/200" Schema path: "/properties/paths/patternProperties/^~1/properties/get/properties/responses/patternPro perties/^([0-9]{3})$|^(default)$/oneOf" ]

Regards

R

[anilsr]

@Rajeev Sakhuja , Thank you for great feedback. It's not supported as of today. Feel free to push a PR if you are interested. You can find source code here.

[gargi_talukdar]

Hi @Anil Sagar,

I am trying to use swagger2api tool in order to create api proxy from sample swagger file following the above example but getting error in doing so. I have attached the screenshot of the error. apigeeerror.jpg. please let me know if I am missing anything here.

[anilsr]

@GargiTalukdar , I haven't tested same on windows. Can you please try on linux / mac ? Seems like bundle generation is successful by looking at console output. You can see apibundle (zip / folder) by navigating to location mentioned in console output. Find the bundle and manually create API Proxy in apigee edge using the "Proxy Bundle" option in create api proxy screen. See if that works.

[anilsr]

BTB, Apigee Edge now have openapi option to create API Proxy from Open API (Swagger). Did you try same instead of using my tool which was created before this feature is available in Apigee Edge ?

[gargi_talukdar]

@Anil SagarI checked the proxy bundle and it does not seems to be proper as petStore folder that gets created has one folder called apiproxy and another zipfolder with the same name . Also petStore is not a zip folder.

I was not aware of the openapi option. Just checked. Will use it for proxy creation. Thanks for the information.

[#16]

Hi @Anil Sagar,

Is there a published roadmap for the expansion of supported policies and policy attachment?

[anilsr]

@Joe Russo , Unfortunately, As of today, no plans. But, good thing is some of the users started contributing to open source tool with more policy support. See github issue here which talks about CORS support. Would love to see more contributions from community.

[anilsr]

@mikael.mellgren , We have updated project name to openapi2apigee. Make necessary changes to docker images if any when you get time. Thank you.

[parna]

@Anil Sagar

Hey Anil, Was trying to use the tool & found the attached error with different swagger specs. Do I have the wrong version? or missing something.

screen-shot-2016-09-16-at-102157-am.png

[anilsr]

@parna@apigee.com , Can you please post as a new question so that t will be helpful for others ?

[#21]

Tool is very good, but I got a couple of questions, in the swagger file I got the path defined as below:

paths: { /v1/source: ... }

The tool is replacing that path by the proxy name, so if I named the proxy as "foo", then the path on default.xml looks like this:

<HTTPProxyConnection> <BasePath>/test</BasePath> <VirtualHost>default</VirtualHost> <VirtualHost>secure</VirtualHost> </HTTPProxyConnection>

And I need to preserve /v1/source

Any suggestion?

Another question I got is regarding with the command line options, can you please provide a basic doc on all the options? or what we got in the sample is demoing the entire option set?

Thanks!

[pravallikamusal]

I have one question that what are Bamboo CICD tools(Global tools which Supports to deploy APIGEE) required?

[#23]

Awesome tool.. Thanks @Anil Sagar

Could you help me to have WSDL file as a string point to create API proxies with this module.

[anilsr]

@Siddhesh

Above tool doesn't support wsdl. Apigee Edge UI API Proxy creation wizard supports wsdl to API Proxy out of the box.

[#25]

@Anil Sagar

Yes. I have used Apigee Edge UI to create api proxy from WSDL.

One of our clients wanted to know if we can automate this process through any scripts.

Even any management API is not available for this process.

[kasiviswanathpu]

Hi Anil,

Great tool, yet to try. I came across this article when I am searching for if there is a tool to generate smart docs using swagger.yaml without even logging into dev portal.

Let me know if this tool will work to generate smart docs of API proxy with swagger.yaml without logging into dev portal. Please let me know and that will help me what I am looking for.

thank,

Vissu

[anilsr]

@Kasiviswanath Pusarapu , Above tool will help to create API Proxies.

Please see solution here for publishing smartdocs using swagger.yaml without logging into Developer Portal leveraging APIs exposed by module mentioned in the link.

[bbhatia]

Does this tool support user token in case org is behind saml?

[aishwaryakozhis]

@Anil Sagar @ Google Am trying to create a CI/CD pipeline in VSTS using this tool. All examples provide a local folder where the proxy bundle gets generated, but i need to create the proxy directly on Edge. Could you please guide me how to use the command in that case?

[nagashree_b]

@Aishwarya Kozhisherry - Usually a CI/CD pipeline works on a code repo and builds and deploys the code to the respective environment. Same is the case with Apigee as well. The API proxy code from a repo will get pushed as a proxy bundle to the Apigee environment.

The openAPI2Apigee tool generates the API proxy code, which you then need to deploy to APigee environment using the Apigee maven deploy plugin or apigeetool nodejs module.

The ideal way would be to create the api proxy code using the openAPI2Apigee tool, push the api proxy code to a repo and have CI enabled for that repo. The CI/CD can use the maven plugin or the nodejs module mentioned above to push the API proxy bundle to Apigee and then deploy it.

I have built CI/CD pipelines for Apigee on Azure devops on the same lines as I have outlined above.

If you can create a separate post with details of your requirement, it would be easier to help.

[aishwaryakozhis]

@Nagashree B Thanks. I was also trying something similar. I have posted the details in a separate question as well.

https://community.apigee.com/questions/66279/azure-devops-cicd-on-apigee-edge.html

I am trying to use Edge Management APIs to sync the Edge proxies with Git. Please let me know if you tried anything similar, or what was your approach.

[nathanaw]

Hi Anil, like to know if my YAML file has Required fields defined, when I imported the YAML into Apigee, will these required fields automatically become validation rules/policies? Is there such functionality today?

Thank you in advance.

Nathan Aw

[pascal_baehler]

Hi Anil

Is it planed to release a version which is supporting openapi 3.0.0 spec?

Thanks,

Pascal