Hello Everyone,
We now have couple of new Swagger tools that will help you create and document your Apigee Edge API proxies. This article answers some frequently asked questions related to working with both the tools.
Q: What is swagger2api?
A: swagger2api lets you generate an Edge API proxy from a Swagger 2.0 specification. It also supports Apigee-127 extensions. That means you can convert an Apigee-127 application to an API proxy with policies support.
Q: What is apigee2swagger?
A: apigee2swagger lets you generate a Swagger 2.0 specification from Edge API proxies. It DOES NOT support Apigee-127 extensions. No policies information is captured in the Swagger 2.0 specification.
Q: Is there any relationship between swagger2api and apigee2swagger?
A: Both are independent of each other. One converts Swagger 2.0 > API proxies, the other converts API proxies > Swagger 2.0. These tools SHOULD NOT be used for Swagger 2.0 > Apigee Edge > Swagger 2.0.
Q: Why you should NOT use the tools for Swagger 2.0 > Apigee Edge > Swagger 2.0?
A: Edge API proxies don't store metadata associated with Swagger 2.0, such as request variables, response schemas, and success codes. When you convert Swagger 2.0 specifications to API proxies, that information is lost and it won't be available when you generate swagger 2.0 from those API proxies.
Q: Can I use swagger2api for incremental development?
A: No. Currently, swagger2api doesn't sync changes made in Apigee Edge once you deploy your API proxy. The moment you deploy the API proxy, it creates a new revision and doesn't copy changes you have made in earlier revisions. The tool is useful only when you start an API proxy and should not be used for incremental development.
Q: Does apigee2swagger generate 100% documentation for my API docs?
A: No. Currently it generates around 70-80% documentation for your APIs. Since an Edge API proxy is a proxy, not an actual API, it doesn't have information like request variables, response schemas, expected status codes, and so on. You need to edit the Swagger 2.0 specification generated from apigee2swagger to make the documentation 100%.
Q: Can i use swagger2api for incremental development?
A: No. It should not be used to update already existing Swagger 2.0 specifications with any custom changes. If there are no custom changes to your specifications and 70% use cases are enough for you, then you can go ahead and use swagger2api for incremental releases. It will be useful for quick-start documentation when you are doing it the first time.
Q: Can I use apigee2swagger to kickstart my Apigee Developer Portal SmartDocs?
A: Yes, absolutely. It saves 70% of your effort in generating SmartDocs. It automatically parses your conditional flows and proxy endpoints to generate Swagger 2.0 specifications.
Keep us posted if you have any more queries related to using these tools.
Cheers,
Anil Sagar
LinkedIn
Twitter
