OpenAPI Spec (Swagger Spec) Generator - Online tool to generate OpenAPI Spec from API calls

[anilsr]

UPDATE: This UI tool is deprecated. Use command line tool if you are interested in generating OpenAPI Spec 2.0 https://github.com/anil614sagar/api2swagger

Hello Everyone,

Software books advise us to write specs & use a design first approach, but when it comes to reality many developers (like me) love to code first and worry about such things later I am sure many of your APIs follow same strategy.

From my experience, many API Programs that use Apigee Edge, whether in the Apigee-managed cloud or in a customer-managed cluster, have very carefully designed and implemented APIs. Unfortunately, what is often missing is an OpenAPI specification for those APIs. An OpenAPI spec is basically a “model” of the API; a machine-readable description of what the API accepts and returns.

Without a spec, developers who build and publish these APIs spend a bunch of time doing “busy work”, such as hand-crafting documentation, hand-crafting mock servers or test clients. Imagine an API that has 15 verbs + URI Path pairs. Each pair with a POST or PUT accepts a payload. Would you want to hand-craft all the tests that exercise such an API? Would you want to hand-edit a mock server? Surely not.

The good news: With an OpenAPI spec, those kinds of things can be automated. You can use an OpenAPI spec to generate documentation using SmartDocs, or to automatically create test cases using Apigee Test, or to create an interactive test client, or even to automatically create API Proxies in Apigee Edge. Having an Open API spec document saves a lot of time for the developers of APIs & improves re-usability.

It’s easy to see the value in an OpenAPI specification for an interface. So why don’t developers always have them for every API they publish? It’s simple: there is a learning curve understanding the spec. Writing a spec from scratch is a pain in the A…ummm.. neck .

If you have followed along, you may have seen the api2swagger command line tool. (It was named before the rename of Swagger to OpenAPI Specification). It basically produced an OpenAPI Spec from an existing Apigee Edge API Proxy.

Apigee is now releasing a new tool, a UI version this converter, with cloud storage capability for your OpenApi Spec. This should help you collaborate with teams online.

Open API Spec Gen (Beta):

Navigate To : http://specgen.apistudio.io/

Usage :

It’s more / less similar to rest clients you have used. You make an API call & tool will capture API runtime information, helps you generate openAPI Spec within few seconds.

Let’s generate Open API Spec for Apigee Management Developers API & see how it works,

Step 1 : Run API

In this step, you will make runtime API call. Let’s start with List Developers API,

Click on Next Step below the headers in right side to navigate further in the spec generation process.

Step 2 : Program Info

In this step, you will provide Open API Spec API Program information like title, descript, version, contact, license etc. We autofill almost 80 %, 20 % you have to make changes.

As you can see, almost i can skip any changes in this screen & hit next step.

Step 3 : API Info

In this step, you will define basePath & some meta info about API, Use drag & drop slider to pick base path & observer API Path getting changed automatically for you. You can also see by default scheme is selected from API call you made. Make changes as necessary.

• Select basePath as /v1/organizations
• Edit OperationId & Summary
• Hit Next Step on top.

Step 4 : Headers Info

In this step, you will provide information about your API Call headers which are captured from your API call in the first step (Run API).

• Once you are done with changes, Hit Next Step.

Step 5 : Params Info

In this step, you will provide metadata information of Query Params & Form Params. Since we did a get call without any query params you don’t see any data here. Click Next Step to continue.

Step 6 : API Path Info

In this step, you will select dynamic params in the API Path. As you can see, above API call has Org Name which is dynamic. Just click on orgname in the API Path & add meta information.

Step 7: Open API Spec

That’s it. See your generated Open API Spec. Make any changes if needed inside the editor & click on save changes. Manual changes can be done here.

Step 8 : View Docs

Swagger UI like view where you can see list of resources & try out if CORS enabled.

Step 9 : Apigee

In this step, you will get to know what Apigee Does & Links to Apigee related products.

That simple, I am sure, you can able to generate OpenAPI Spec within 60 seconds.

FAQ :

Q: How can I save my generated spec & revisit later to add more resources to spec?

A: Make sure you bookmark the unique URL & use same to edit the spec later point of time.

Q : How can I add more resources to existing spec ?

A : Click on Home Page link in menu to add more resources to existing project, you will notice hostname & basePath auto filled. Just provide new API Path & start generating Open API Spec & Update existing spec.

Q : How can I download openApiSpec that i have generated ?

A :

• Navigate to http://specgen.apistudio.io/v1/runApi/openApi/{32 Characters ID} & download the spec by saving the page.
• We now have download spec button in OpenAPI Spec page tab.

Q : How can I share openApiSpec with others ?

A : Copy the URL from browser which has 32 char UUID like http://specgen.apistudio.io/open-api/{32 Characters UUID}/api-spec & share with others. Also, Save using bookmarks for future reference.

Q : How can I start a new project ?

A: Click on New Project Link in Main Menu

Q : Do you store API runtime information in server ?

A : NO, We don’t store runtime information in server, it’s stored in browser local storage. Data is deleted from browser local storage when you close the browser. We just make a call from server & return the data to browser local storage.

Q : What do you store in server ?

A : Generated OpenAPI spec is stored in server.

Q : Any restrictions as of today ?

A: Yes, Supports only JSON response. Supports only, GET , POST, PUT, DELETE. Hopefully, It solves 80% of your use cases. Remaining 20 % use Editor in Step 7.

Q : Why do you built same as new tool instead of integrating into API Studio ?

A: End goal is to integrate same into API Studio. Hopefully, we will see same one day.

Keep me posted if you have any queries using comments.

[jonesfloyd]

SO cool! I wanna try it, but I get a connection refusal.

[anilsr]

@Floyd Jones , Can you try now ? For some reason node process got terminated.. Restarted same..

[jonesfloyd]

Bingo! Thanks, @Anil Sagar!

[anilsr]

@Floyd Jones , Seems like when someone jumps the queue (spec generation steps) tries to do something, it breaks.Need to do better error handling Will try to fix same tomorrow. Keep me posted with your feedback if any. As long as, you follow steps in order you should be good.

[jonesfloyd]

Man, this is brilliant, @Anil Sagar. Kick a**. I also tried it with a management API. I also wanted to see if I could generate an API proxy with the JSON.

I know it can be done with your Swagger2API tool.

See Anil’s comment below before going the Github route.

But I did it successfully like this:

1. Copy the JSON at the Open API Spec stage, and save as myspec.json locally.

2. Push the file to Github.

3. In the proxy wizard, create a Reverse Proxy with “Use OpenAPI”, and enter the URL to my JSON file in Github with https://raw.githubusercontent.com/. You can get this by viewing the file in Github and clicking the Raw.

   

4. Create the proxy as a Passthrough.

5. In the cURL call, pass my org admin creds using -H “Authorization: Basic <base64_creds>”.

I know proxy creation will get easier when Docstore is up and running

The fabulous @Liz Lynch just published a great tutorial on creating proxies with OpenAPI specs:

http://docs.apigee.com/tutorials/create-api-proxy-openapi-spec

[anilsr]

Thank you @Floyd Jones for using the tool & very valuable feedback.

JUST FYI, Tool is powered by APIs, you don’t need to copy spec & host in github. You can directly access via API, http://specgen.apistudio.io/v1/runApi/openApi/{{UUID}} like http://specgen.apistudio.io/v1/runApi/openApi/b0318ae2-dbdf-4cda-8241-7bc1f8934606 .

You can give above URL directly in Apigee Edge to generate API Proxies.

Thank you again for the feedback. Love it!!

Great to know about @Liz Lynch doc article on creating proxies with OpenAPI spec.

[anilsr]

Thank you @Dino & @Marsh Gardiner for review & edits.

[kurtkanaskie]

Well that explains it, I tried going to a previous step to make a correction, now I get ERR_EMPTY_RESPONSE.

[anilsr]

@Kurt Kanaskie , Thank you for valuable feedback. Can you please let me know which step to which step resulted in above error ? I know it causes problem when you try to edit “Path Info - Step 6” , Any other steps ?

[jonesfloyd]

Brilliant! Thanks!

[anonymous]

Pretty cool @Anil Sagar ! Good stuff!

It generated Swagger file with no issues. However, where did the spec go? Or is the tool meant to test the wizard only? I loved that you embedded Swagger-UI into the tool tool and you can try it from there. Also, is this a Node.js based app? is this something that can be shared on a repo?

[anilsr]

@Diego Zuluaga , You can click on “Open API Spec” tab (Step 7) to see the spec anytime. You can also access same using “http://specgen.apistudio.io/v1/runApi/openApi/{{UUID}}” , yes, It’s nodejs based app, i will share the repo soon. Keep me posted.

[anonymous]

Awesome! One suggestion is to make obvious the links at the end of the wizard, so people know that the outcome gets stored and users can go back and see the spec along with swagger-ui at any point in time.

The use case for Nucleus team is pretty straightforward. We already have the Swagger/OAS file. And we want to generate executables docs with a tool like openAPIgen and we want to run it locally or in a Node.js container. However, when I try the spec, I get this error:

The link to our OAS Spec can be found here:

http://petstore.swagger.io/?url=https://nucleus-api-test.apigee.com/nucleus/edge/api-docs#/

It looks like by default, express accepts smaller payloads. According to this SO thread, this is configurable.

app.use(express.json({limit: '50mb'}));
app.use(express.urlencoded({limit: '50mb'})); 

Would you mind adjusting it to try it again?

One more thing to learn about the implementation of your tool, how do you store specs and files? through the filesystem or a database?

[anilsr]

Thanks @Diego Zuluaga , Above limit issue has been taken care.

[anilsr]

@Brian , @Rajat Agarwal , @Thomas Lippuner FYI

[anonymous]

@Anil Sagar

This online tool is so cool to generate Swagger spec.

However,I am not able to use it for our APIs as they are not exposed to public and hence unable to hit them through online tool.

Can you please let me know if there is offline version of this tool so that I can download ,install and use it?

[anonymous]

@Anil Sagar

Also..for POST,where to give the request payload?

[anilsr]

@RK4 , Glad you like it & it’s helpful.

Regarding your queries,

• Private APIs, We don’t have UI based tool. It’s not open sourced yet. You need to use api2swagger command line tool to work with private APIs onpremises.
• For POST, once you select “POST/PUT/DELETE” verb you will see body section below the textbox. see attached screenshot for example.

[kurtkanaskie]

+1 on the link to get the spec, maybe as info.x-location