Problem importing Swagger docs with SmartDocs

[mrios]

Hello everyone, I'm trying to add a new model through SmartDocs without luck so maybe somebody can help me. In my company we have all the API docs (built with Swagger 1.2) in an internal url that looks like http://BASE_URL/api-docs. When I open that URL with the browser it looks like this:

{
   apiVersion: "1.0",
   apis: [
       {
           description: "Basic Error Controller",
           path: "/default/basic-error-controller",
           position: 0
       },
   ]
   authorizations: { },
   info: {
       contact: "Contact Email",
       description: "Api Description",
       license: "Licence Type",
       licenseUrl: "License URL",
       termsOfServiceUrl: "Api terms of service",
       title: "default Title"
   },
   swaggerVersion: "1.2"
} 

Actually there are more elements in the apis array but for simplicity I just paste this one. Also, I have access to the URL http://BASE_URL/api-docs/default/basic-error-controller and it shows information about that service and everything looks good. Actually, we can see the documentation with the Swagger UI and it works fine.

The Problem:

To create the new model I go to Add Model from SmartDocs and then I'm using the import operation. Once there, I choose Swagger format and I add the URL http://BASE_URL/api-docs. The import seems to work because it says "The swagger data has been imported into the model" and I can see the Resources and Methods. However, the path looks brooken because when I render the node and I opened it (so I'm looking at the api documentation view) the Resource URL shows //_something where something is the name method imported. It also shows in some cases 2 content-type header parameters and when I try to send the request it says "Working ..." but never come back (I think this is related to the Resource URL)

We are running the Dev Portal in our private cloud.

We are using Swagger 1.2

Does anyone have any idea why this is happening?

Thanks, Matias

[gnanasekaran]

Hi Matias,

What is your opdk version?

To use 'try it' functionality - you need to run a script /APIGEE_HOME/bin/setup-smartdocs.sh -

Also, check your javascript console in your browser?

Thanks,

Mukundha

[mrios]

Hi Mukundha,

Thanks for the quick response.

I'm not sure how to check that but the person that installed the Dev Portal told me is DeveloperServices-4.14.07.05 Does it makes sense?

What do you call "try it" functionality? Is it related to install SmartDocs in Edge?

Thanks,

-Matias

[gnanasekaran]

Yes Matias, the version looks right.

The 'try it' function is basically the one that allows you to send request and view request and response.

There are 2 parts to it,

1. Documented in the Install Config Guide, it involves running the setup-smartdocs script

2. Portal configuration to point to your on-premise installation - http://apigee.com/docs/developer-services/content/using-smartdocs-document-apis#configuringthesmartd...

Both the above are for the second issue you reported.

--

For the first issue,

"Resource URL shows //_something where something is the name method imported"

I am not sure why its happening, can you also post the contents of /api-docs/default/basic-error-controller?

Thanks,

[anilsr · Accepted solution]

Dear @Matias ,

Welcome to Apigee Community 🙂

Base path is missing from your Swagger 1.2 spec. Since no base path is mentioned try it feature results in an error.

That's also the reason why resource URL shows as //

For Example, See below 1.2 spec,

{
  "swaggerVersion": "1.2",
  "basePath": "http://localhost:8000/greetings",
  "apis": [
    {
      "path": "/hello/{subject}",
      "operations": [
        {
          "method": "GET",
          "summary": "Greet our subject with hello!",
          "type": "string",
          "nickname": "helloSubject",
          "parameters": [
            {
              "name": "subject",
              "description": "The subject to be greeted.",
              "required": true,
              "type": "string",
              "paramType": "path"
            }
          ]
        }
      ]
    }
  ],
  "models": {}
}

[mrios]

Thanks @Anil Sagar!

As you said, the problem was related to the basePath in the Swagger spec.

Took me a while to configure it properly but the import it's working now.

Thanks!

[anilsr]

@Matias , Glad your issue is resolved 🙂