Layer7 API Management

Expand all | Collapse all

How to associate documentation to APIs on Developer Portal?

Jump to Best Answer
  • 1.  How to associate documentation to APIs on Developer Portal?

    Posted 05-03-2016 08:30 AM

    Hi,

       I would like to know how to publish documentation for the services and APIs already available on the API Gateway?

     

       Scenario is:

       a. There are a mix of APIs (RESTful) and Web Services (SOAP) on CA API Gateway v8.3

       b. Portal v3.5 is now installed and integrated with the Gateway

       c. One each of RESTful API and Web Service is enabled for Portal Management

       d. The services appear on Portal

       e. The services are enabled on Portal without documentation (i.e wsdl or wadl or raml) and published

       f.  Services are visible on portal

     

       Issue is at step e.

       SOAP Service:

       1. When enabling a SOAP service, if wsdl is being supplied (the one on which the service was built), it returns some wsdl parsing error (ResourceSet not found). The wsdl is very much a valid one

        2. If the same wsdl is used to create a SOAP Service from Add New -> SOAP Service then the service gets created along with documentation and published on Gateway (however this is not what is intended)

        3. If I create an independent documentation page and associate it to the API and publish it the same is not reflected on Manage APIs page i.e. there is no hyper link on the API Name to the documentation

     

       RESTful Service:

       1. There is no wadl associated to the Web API

       2. Hence created a separate static documentation and tried to associate it to the API. This again does not work

     

      Can someone help me in resolving this riddle of publishing the documentation of the Services and API already existing on Gateway? This is urgent and required for a demonstration, appreciate a quick response.

     

    Regards,

    Trinath



  • 2.  Re: How to associate documentation to APIs on Developer Portal?

    Broadcom Employee
    Posted 05-05-2016 12:31 AM

    Hi Trinath,

    Did you try login portal dashboard -> APIS -> select an existing API and select Edit -> on Details tab, look at "Create/Update Interactive Documentation" section, you should be able to upload wadl/raml file here.

     

    Regards,

    Mark



  • 3.  Re: How to associate documentation to APIs on Developer Portal?

    Posted 05-25-2016 11:29 AM

    Hi Mark,

       I did the same for wsdl and it did not get uploaded successfully. I did not do it with wadl as we don't have wadl associated to the REST services we had built. However if I create a document and associate to API it still wont work.

     

    Regards,

    Trinath



  • 4.  Re: How to associate documentation to APIs on Developer Portal?

    Broadcom Employee
    Posted 05-30-2016 02:12 AM

    Hi Trinath,

    No matter wsdl or wadl, it can be uploaded when you edit, or enable the api.

    You said the you failed to upload the wsdl, was there any error? You may attach a screenshot to show the error.

     

    Regards,

    Mark



  • 5.  Re: How to associate documentation to APIs on Developer Portal?
    Best Answer

    Posted 06-06-2016 02:01 AM

    Hi,

      There is no option for a SOAP Service to upload a WSDL document in v8.3 Please see the screen shot below, we need to upload a RAML or WADL even for a SOAP Service.

     

    soap-service-edit.png

         This is a bug in Gateway and it is being fixed as part of CR2. Here is the response from CA (Dana Crane - Product Manager).

    "...here are the features for the upcoming Portal 3.5 CR2 (aiming at a June 14 GA):

     

    • Portal Recognizes SOAP Services
      • The “Set as Portal Managed” assertion automatically identifies API type, allowing the Portal to properly display the API as either SOAP or REST. As a result, the API descriptor now correctly prompts you to upload a WSDL file for SOAP services, or a WADL/RAML file for REST APIs. 
    • Multi-Part SOAP Service Artifact Upload
      • Multiple files that describe a SOAP service can be uploaded to the Portal, including primary WSDL, embedded/linked sub- WSDLs, XSDs, etc
    • Auto-doc Artifact Download
      • The automatically created documentation for SOAP services provides a link to download all files associated with the service as a single zip file
    • Security Fixes
      • In certain specific cases, the registration Captcha could be bypassed; Account Manager role could be compromised; and API Owner groups could activate any API. These security holes have been patched.            

    .... "

     

        Dana has also acknowledged that my other question was also a bug and provided us with a workaround.

       My original question: If I create an independent documentation page and associate it to the API and publish it the same is not reflected on Manage APIs page i.e. there is no hyper link on the API Name to the documentation

      Work around provided by Dana:

    The other issue mentioned on the call was the fact that APIs in the API Catalog could not be hyperlinked to manual documentation pages. I’ve verified this, and can offer the following workaround:

    1. Log into your Portal as Admin
    2. Navigate to the Manage APIs page
    3. For an API, click on the gear icon dropdown and right click (please note this is RIGHT click NOT LEFT click) on Edit in order to open the link in a new tab
    4. In the documentation entry box (highlighted in red below) enter the URL to the API’s manually created doc page. For example, if your page is located at http://myportal.com/documentation/API01 you would enter API01
    5. Click the Save button and test it out

    error1.png

        This work around worked for me. So I consider this thread to be answered as this was what I was looking for, albeit a workaround.

        Providing this information in the thread so that it could be of use to someone else!

     

    Regards,

    Trinath