How can I generate Swagger Spec or SmartDocs JSON for the proxies on edge?

[#1]

I have Edge and Dev Portal installed (private cloud, 15.04) with few proxies in Edge. Apparently Dev Portal is providing 3 ways to import documentation for the models. I have questions reg. these options.

WADL - I found this tool to generate the WADL file; has some dependencies and some limitations

Swagger - this needs the Swagger URL - what would be this URL?

SmartDocs JSON - how do I get this?

Please let me know what I am missing in terms of Swagger setup or anything else.

[gnanasekaran]

@Rangaraya S Komaragiri,

1. SmartDocs JSON is a internal json representation, You don need to know it and depend on it, unless you are migrating existing smartdocs from another Edge org.

If you want to see how this looks like, try

curl -v http://managementserver:8080/v1/o/{org}/apimodels/{model}/revisions/{revision}|1/resources

2. Swagger URL - this is Swagger 1.2 Resource Listing URL

For just generating Smartdocs from proxies, this tool would suffice - let me know if you run into issues

Thanks,

[#3]

@Mukundha Madhavan, thank you for your quick response.

I've used your tool and was able to generate the docs via WADL, but I have few concerns:

1) dependency on node.js and how do I integrate this in my build & deploy process to update the documentation for a proxy revision?

2) the tool emits the Header Parameter requirements from the policies that I've used within a proxy - e.g., the SpikeArrest policy has two headers (could've been generated by default) - "some-header-name" and "weight".

My biggest concern is that - I was under the impression that Edge can auto-generate Swagger spec for the proxies and that DevPortal should be able to auto-extract the Swagger spec of the published versions of the proxies since it can talk to the management server. I am surprised that we need to manually go through this exercise every time we create/revise proxies.

Could you point me to some documentation on the workflow around maintaining the documentation on Dev Portal on a regular basis?

[gnanasekaran]

you are right @Rangaraya S Komaragiri, i think this is in the product roapmap - pls connect with your customer success team for more details

on the concerns, 1-> cannot be avoided, but 2 can be easily overcome by modifying the script or removing unused params in your proxies

[anilsr]

Now, We have a couple of tools to generate OpenAPI Spec (Swagger) spec for APIs. Please find more about same below.

• Open API Spec Generator - http://specgen.apistudio.io/
  • Automate the API lifecycle by generating an Open API (formerly known as Swagger) specification. This tool helps you generate Open API spec from existing APIs. 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.
• Apigee2OpenAPI - https://www.npmjs.com/package/apigee2openapi
  • Apigee Edge Proxy to OpenAPI 2.0 (formerly known as Swagger) conversion tool.
  • How to use - https://community.apigee.com/articles/10044/apigee2openapi-a-nodejs-command-line-tool-to-gener.html