How to download OpenAPI Specification from Developer Portal

garysole
Participant II

How can I expose the actual Swagger Spec (JSON/YAML) on the Developer Portal.

I can upload the Spec, set a SNAPSHOT for the Developer Portal and view the documentation.

I would like a developer to have the ability to download the Spec and be able to use it to Generate Client code in the language of their choosing using swagger.io or some other tool.

1 11 3,753
11 REPLIES 11

Hi @Gary Sole

Welcome to the community !!

How about exposing the OpenAPI spec as an endpoint (say /{basepath}/api-docs or something) so that

1) You have control of the spec within the API

2) No additional process required within dev portal for this

3) Its a URL that can be imported directly within Open API editors

NOTE: Make sure this end point has the right security options (either public or basic security, etc) so that it can be accessible for developers to import. You can then provide some documentation that can appear in the dev portal for developers to import the api-docs and generate client code

Hope this helps !

How could I reference the same API Specification that generates the documentation the developer is viewing. I looked through the APIGee API Specs, but could not find an API where I could source the API.

You can create another conditional flow in your API proxy (say GET /api-docs), store the Open API json within it and point this resource to that content (set the json as response using JS policy). You can also include the /api-docs in your spec so that it comes in the documentation when you upload it to dev portal

If you inspect the network resources of the developer tools in your browser when loading the API reference for a product published on a new (integrated) API portal, then you should see the published copy of the JSON specification that is loaded.

It is a story in our backlog to optionally expose the spec within the documentation. Hearing that it might be useful to you helps us prioritize, thanks.

I would definitely like this feature. My inhouse API publishes a swagger.json file but its paths are all wrong. The docs on the Apigee hosted portal is built from a modified version of that and I'd like to easily share that modified spec to the users.

Thank you. I understand the ability to expose the JSON Swagger Spec through another end-point. I do like the idea of including the /api-docs in the Spec.

What it appears though, is that I will need to manually ensure that the spec I expose through the endpoint and the API Spec SNAPSHOT I setup in the Dev Portal are identical. There does not appear to be an APIGee API where I can get the SNAPSHOT spec content that generates the API documentation, and expose that through the endpoint.

I see what you are asking.. Quick question - are you using the new User Experience of Apigee Edge (apigee.com/edge)? If yes, did you generate the proxy from the OpenAPI spec within the Edge UI ?

Yes - I am using the new user experience, and I do have an API Proxy generated from an OpenAPI spec within the Edge UI.

michaelveit
Participant III

It is possible to download the openAPI. Use F12 in your browser when opening the spec editor, and you will see the URL. However, you don't get it for free due to security constraints.

How to put all pieces together:

  • Fetch the associated ID from your proxy. For the Apigee test accounts, you can use such an URL in order to fetch the association.json:
    https://apigee.com/ws/proxy/organizations/YOUR_TEST_ACCOUNT/apis/Mock-Target-API/revisions/1/resourcefiles/openapi/association.json
  • The association.json contains the ID, such as: "url": "/c3Rvc-ZG9j-127356/content". This JSON is also within the ZIP file when you download the proxy ZIP via management API.
  • You can call the spec editor using your ID, such as:
    https://apigee.com/organizations/YOUR_TEST_ACCOUNT//specs/homeFolder/editor/c3Rvc-ZG9j-127356
  • If you enable browser's F12, you can see that the following request downloaded the openAPI spec:
    https://apigee.com/c3Rvc-ZG9j-127356/content
  • You cannot call the URL directly due to missing headers. E.g. security token is missing if you simply paste URL in browser.
    In browser's F12, you can see the headers sent with the request. For programmatic calls, you need to establish the security token and send it along with the request, as cookie or HTTP header. See cookie "access_token", "logon_session" etc.

Surfacing a link to the raw spec is something we're considering as a future story, but thanks for posting how this can be accomplished in the short term.

Thanks Michael Veit this really helped