How can I upload swagger specs and API documentation?

Not applicable

I want to avoid working with the Apigee Edge UI. Instead, I want to keep the proxies and their artefacts under sourcecontrol, and use the Management API to upload updates. This works well with proxy definitions (xml) and resource-files. However, the swagger yaml-file is tightly bound to the proxy itself, and I want to keep it under source-control just like the other files (ESPECIALLY since there is no revision-control for the specs in the Edge UI). So, my first question is:

1. How can I upload new versions of the swagger specs?

And secondly:

2. How can I script the generation of the API-documentation from the swagger spec? Today, I have to do this manually in the Drupal-based developer-portal. Actually, it doesn't quite work there either, or - it works, but with some error messages along the way. But I manage to get it out there, at least. But when there is an update to the swagger spec, I need to manually delete the API documentation, and then add/re-generate the documentation on the developer portal again. Not exactly a streamlined process. I want to know if Apigee as a platform has support for creating the documentation through an API call, so that I can automate this process. I know I can produce documentation locally (using bootprint-openapi for example), but this triggers yet another question...

And finally:

Is there an API for working with the developer portal? Can I keep the definition of the portal locally (css-files, images, etc, etc), under source control, and then upload modified files to the portal through some API? Or more specifically - is it possible to publish API documentation to the developer portal, through HTTP posts, FTP, or some other means? I want to automate the process of working with my APIs - including the swagger spec and corresponding documentation - as much as possible.

Any input as to how I can automate and streamline this process is much appreciated.

2 8 3,458
8 REPLIES 8

regarding

Is there an API for working with the developer portal?

Which developer portal? There are two today... the "new" devportal which was launched about a year ago, and the Drupal-based devportal which is older.

Which one are you trying to automate?

Hi Dino,

I believe Bjorn and his company are using the Drupal portal.

Many thanks,

Sean

Hi Bjorn,

Hope you are well!!

As a (real) developer, I also enjoy developing using local tools instead of the UI. I use Vim and Management APIs via Maven and other Plugins to develop locally.

Have you checked out the Smartdocs Service?

This is an Open Source module that allows you to upload Dev Portal Docs via APIs. This only applies to Swagger specs, however it is also possible to store Drupal artifacts such as CSS, Images etc. in Source Control in a similar manner.

Please have a look at this module and see if it meets your needs. Hopefully it will solve the 'SmartDocs' part of your puzzle, and we can get more assistance for the static content and other Dev Portal requirements you have. Please reach out directly if you have any problems!

Many Thanks!

Sean

Thanx for the tip, but it seems to me that the Smartdocs Service applies to "old" devportals? Mine is built using the New Edge experience...

Also looking for the management API call docs for how to query the new API 'specs' as exposed in the new mgt portal UI.

Even i am unable to find any management api to upload swagger to New Dev Portal.Is there any feature available?

Not applicable

Actually, I didn't even know that there existed two types of portals. I have created my devportal using the New Edge experience. I have found this doc, which lists the differences between the old and the new: https://docs-new.apigee.com/new-versus-classic-edge#portal-feature-comparison

michaelveit
Participant III

Still not able to find any possibility to upload spec via management API. I have expected to find anything which I could do in the GUI. Furthermore, the API proxy upload file format is not documented in the management API. There should be a link to the file format specification, or a name of the format definition, if it's generic. Or need to specify that user must create the API proxy in GUI, then export, if you want the definition remaining uncovered.