Can Smartdocs be created from a Swagger 2 document?

Not applicable

I see that smartdocs supports importing Swagger but I did not see anywhere what version of Swagger it supports. I also saw other references to it supporting only the 1.2 and 2.0 was on the way.

I have a few questions:

  • Does smartdocs support importing Swagger 2.0 yet?
  • If not, any idea when support for Swagger 2.0 will be added?
  • if it is not currently supported, what should i do in the meantime? Is there a way to manually enter info for a SmartDoc while waiting for 2.0 support?
  • When importing WADL or SmartDocs JSON you have the option to use a file or a url, why is the file option not offered when importing a swagger document? It would be easier.
  • When importing a swagger doc, what format does the document need to be in? Can it be YAML ir does it have to be JSON?
  • I am using a127 and have deployed an API to Apigee Edge, is there a way to get a URL from the deployed API on Apigee to the swagger doc?

Thanks!

...Ed

Solved Solved
4 23 3,910
2 ACCEPTED SOLUTIONS

Hi @Ed McPadden. SmartDocs was released before there was a Swagger 2, so it sounds like we may have some documentation we should clean up. Thanks for pointing out that confusion.

We depend on the swagger-codegen project, which only hit M1 in the last couple of weeks. Our development branch has now incorporated this (though it is still a pre-release candidate), so 2.0 import should land within the next few releases, assuming all goes well. It is likely that you'll be able to import YAML or JSON, since they are so interchangeable. Note that 1.x only supported JSON.

Swagger 1.x was a distributed file format, so it requires multiple files. Swagger 1.x convention also expected the descriptions to live alongside the APIs, so importing by URL was the logical approach. Swagger 2 is much more flexible about this, which is great.

HTH,

Marsh

View solution in original post

Dear @Ed McPadden & @Vineet Bhatia ,

We now have Swagger 2.0 support for Apigee Developer Portal SmartDocs. For more details please refer here.

Cheers,

Anil Sagar

View solution in original post

23 REPLIES 23

Hi @Ed McPadden. SmartDocs was released before there was a Swagger 2, so it sounds like we may have some documentation we should clean up. Thanks for pointing out that confusion.

We depend on the swagger-codegen project, which only hit M1 in the last couple of weeks. Our development branch has now incorporated this (though it is still a pre-release candidate), so 2.0 import should land within the next few releases, assuming all goes well. It is likely that you'll be able to import YAML or JSON, since they are so interchangeable. Note that 1.x only supported JSON.

Swagger 1.x was a distributed file format, so it requires multiple files. Swagger 1.x convention also expected the descriptions to live alongside the APIs, so importing by URL was the logical approach. Swagger 2 is much more flexible about this, which is great.

HTH,

Marsh

Great, thanks Marsh ... looking forward to this

Also looking forward to Swagger 2.0 support for SmartDocs.

@Vineet Bhatia, keep in mind that the current Swagger 2.0 support is a "preview". There is a significant update coming soon that will add full security support and bring workflow improvements, including spec uploading and Swagger YAML importing, etc.

Thanks @Marsh Gardiner. We are using on-premise version apigee-OPDK-4.15.01.01 which doesn't have Swagger 2.0 support at all. The cloud dev portal version is 15.03.18.00 and that has Swagger 2.0 "preview" support. Will dev portal be released for on-prem at the same time?

We generally release to the cloud before we release an OPDK version, though that usually happens within a couple of weeks.

Dear @Ed McPadden & @Vineet Bhatia ,

We now have Swagger 2.0 support for Apigee Developer Portal SmartDocs. For more details please refer here.

Cheers,

Anil Sagar

Hi Anil, Is there a patch that needs to be added to the Developer Portal? What do we request to make this work? This is our BuildInfo:

Version: Developer Services 14.08.27.01

Build Number: 90

Build Timestamp: 20140828.2102

SCM Revision: d99ea0042996f1c0ec02c14966be72f56b48e7a0

OPDK Version: 4.14.07.03

Thanks

John

Dear @john.l.dohoney ,

Seems like your version of Developer portal is little old. See release notes and latest versions here. We recommend upgrade your opdk portal to latest versions after taking safe backups.

I am not sure latest version of Developer Portal OPDK supports swagger 2.0 or not. @Marsh Gardiner Does swagger 2.0 support available for OPDK version ?

Cheers,

Anil Sagar

Partial support arrives in the 15.04 release (doesn't include security objects).

Hi @asagar I at the cloud version of dev portal and don't see a way to add Swagger 2.0 spec to Smartdocs. Am I missing something?

- vineet

Dear @Vineet Bhatia ,

What is your cloud developer portal version ? You can check by navigating to "/buildInfo"

Cheers,

Anil Sagar

Version: OPDK-4.15.01.01

Since swagger-codegen is a dependency, and that project didn't have a release candidate until March, I am certain that 4.15.01.01 would not have had any Swagger 2 support on import. The first version that did would be 4.15.04.

Hope that helps, Marsh

Dear @Vineet Bhatia ,

Once you click on Import link for a model you will see an option to provide Swagger 2.0 spec json url.

Currently doesn't support file upload but you can able to provide a URL where swagger 2.0 spec has been uploaded. See below screenshot for reference.

378-swagger.png

Not applicable

I see that 4.15.04 for Developer Portal is GA. Can it import/export Swagger 2.0 now? Has anyone tried this capability in this version?

@john.l.dohoney It is available on the cloud version of DevPortal. On Prem (Private Cloud) version does not have this yet. Its usually a month behind the cloud version. CC @Marsh Gardiner

@Vineet Bhatia and Apigee team: When is the 15.05.27.00 cloud functionality (Smartdocs incl. Swagger 2.0 support) being release as a Private Cloud (was: OPDK) release? The latest (4.15.04.01 from May 23, 2015) does NOT include it yet. An ETA is highly appreciated, we're waiting to adopt this. @David Simons @john.l.dohoney

15.07 is in the QA cycle, but it is overdue. This is in part because of the extra effort involved in making this release support a universal upgrade (basically from any version, within reason). @David Padgett can possibly shed more light on the anticipated release date, but I would expect it in the next 2-3 weeks. (and sorry for the delay!)

Thank you @Marsh Gardiner- and to double-check - you are talking about 4.15.07.xx release of the Developer Services portal for Private Cloud ? That is what we're waiting for upgrading our on-premise install to.

Yes, that's what I meant.