API Docs not auto-generating, unable to take snapshot.

Not applicable

Hello,

I'm trying to get a portal for an api up and running.

The API docs that are "Auto-generated from your OpenApi spec", are not being.

I seem the following console error:

Failed to load resource: the server responded with a status of 404 (Not Found)
jquery-3.1.0.min.js:4 Synchronous XMLHttpRequest on the main thread is deprecated because of its detrimental effects to the end user's experience. For more help, check https://xhr.spec.whatwg.org/.
send @ jquery-3.1.0.min.js:4
jquery-migrate-1.4.1.js:45 JQMIGRATE: jQuery.browser is deprecated
migrateWarn @ jquery-migrate-1.4.1.js:45
jquery-migrate-1.4.1.js:47 console.trace
migrateWarn @ jquery-migrate-1.4.1.js:47
(unknown) url:  /smartdocs/high-school/openapi.json
(unknown) Uncaught ReferenceError: jsyaml is not defined
    at <anonymous>:24685:23
    at Kn (<anonymous>:9:530)
    at Function.<anonymous> (<anonymous>:30:66)
    at Object.createJSONSample (<anonymous>:24681:9)
    at s.render (<anonymous>:23220:78)
    at s.addOperation (<anonymous>:25211:54)
    at s.render (<anonymous>:25187:12)
    at s.addResource (<anonymous>:22861:50)
    at s.render (<anonymous>:22833:12)
    at s.render (<anonymous>:21853:8)

Also when trying to create a snapshot from the API console I get the following error in the chrome console:

console.js?ver=201601270616:1 Error Message: Method Not Allowed
console.js?ver=201601270616:1 Uncaught TypeError: Cannot read property 'replace' of undefined
    at renderCaptureSnapshot (console.js?ver=201601270616:1)
    at Object.error (console.js?ver=201601270616:1)
    at Object.resolveWith [as rejectWith] (jquery-ui_min.js?ver=201601270616:16)
    at w (jquery-ui_min.js?ver=201601270616:16)
    at XMLHttpRequest.d (jquery-ui_min.js?ver=201601270616:16)
renderCaptureSnapshot @ console.js?ver=201601270616:1
error @ console.js?ver=201601270616:1
resolveWith @ jquery-ui_min.js?ver=201601270616:16
w @ jquery-ui_min.js?ver=201601270616:16
d @ jquery-ui_min.js?ver=201601270616:16

I'm just running chrome on Ubuntu and it seems odd to have this many errors...

Solved Solved
1 11 555
1 ACCEPTED SOLUTION

smccormick
Participant I

ok, I think we have tracked down our current problem...there currently is a bug with rendering example JSON strings defined in OpenAPI/Swagger spec yaml files. If you remove those example strings, you will get the spec to render with the default example documentation for your objects (see attached screen shot). We will work on a fix for this to support example JSON objects in the spec (not sure on the turn around time), but removing these example blocks will get you working in the meantime.

specremoveexamples.png

View solution in original post

11 REPLIES 11

smccormick
Participant I

Hi Kevin, If you get a chance, can you try creating your documentation again, using your first set of steps in "The API docs that are "Auto-generated from your OpenApi spec", are not being set." We pushed a release today that should have fixed that error you were seeing. Let us know how it goes. Thanks -Sean

Hi,

Going back into my portal, and clicking 'APIs' still generates the same error.

(unknown) url:  /smartdocs/high-school/openapi.json
(unknown) Uncaught ReferenceError: jsyaml is not defined
    at <anonymous>:24685:23
    at Kn (<anonymous>:9:530)
    at Function.<anonymous> (<anonymous>:30:66)
    at Object.createJSONSample (<anonymous>:24681:9)
    at s.render (<anonymous>:23220:78)
    at s.addOperation (<anonymous>:25211:54)
    at s.render (<anonymous>:25187:12)
    at s.addResource (<anonymous>:22861:50)
    at s.render (<anonymous>:22833:12)
    at s.render (<anonymous>:21853:8)

smccormick
Participant I

We may need to re-snapshot the spec you provided as something may have gotten messed up because of the bug. If possible, would you be able to update the spec associated with your api and this will recreate the snapshot . Steps to follow:

Login to Edge. On the left navigation, find the "Publish" icon and select it. Then find the "Portals" option in the menu and select it. In the list of available portals, click your portal in the list of portals to edit it.

Click the "APIs" icon. Find the api in your api list, hover over it on the right side the "Spec Snapshot Age" reveals an edit menu of icons, and click the second icon that looks like a folder (Manage Snapshot) should come up.

On the left dropdown, click dropdown "choose a different spec..."

On the dialog that pops up, choose "My Specs" and find your spec in the list and click the "Select" button.

Once you are returned to the "manage snapshot" dialog, clickl the Right Caret button ">" until the right input says "Snapshot"

Click "Save"

Upon clicking "Save" and no errors occur, you can return to your live portal and the API documentation should be working.

Please reply back if this does not work and we can figure it out.

Thx

I followed the steps to re-snapshot, and I receive the same error.

Snapshot-ing itself seemed to work fine.

smccormick
Participant I

Quick followup Do you have the spec file available either via local file or via URL? If so, I would like to upload that file again under a different spec name and see if we can get it working that way by associating your api to that new spec that we upload and snapshot.

Thanks

-Sean

Hey Sean,

I started from scratch this morning, new spec, new proxy, new app product, new portal, new api, same console error.

https://scoir-api.apigee.io/apis/high-school/index

smccormick
Participant I

Thanks for trying that. I am inspecting this furthur and will get back to you.

smccormick
Participant I

Hi Kevin,

Quick followup. I was looking thru your OpenAPI.json which I noticed some JSON "examples". While I dont have your original yaml file, am I correct in determining that you have some "example" blocks in your yaml file that contain JSON? ie see "examples:" block below.

    get:
      operationId: getVersionDetailsv2
      summary: Show API version details
      produces:
      - application/json
      responses:
        "200":
          description: |-
            200 203 response
          examples:
            application/json: |-
              {
                  "version": {
                      "status": "CURRENT",
                      "updated": "2011-01-21T11:33:21Z",
                      "media-types": [
                          {
                              "base": "application/xml",
                              "type": "application/vnd.openstack.compute+xml;version=2"
                          },
                          {
                              "base": "application/json",
                              "type": "application/vnd.openstack.compute+json;version=2"
                          }
                      ],
                      "id": "v2.0",
                      "links": [
                          {
                              "href": "http://127.0.0.1:8774/v2/",
                              "rel": "self"
                          },
                          {
                              "href": "http://docs.openstack.org/api/openstack-compute/2/os-compute-devguide-2.pdf",
                              "type": "application/pdf",
                              "rel": "describedby"
                          },
                          {
                              "href": "http://docs.openstack.org/api/openstack-compute/2/wadl/os-compute-2.wadl",
                              "type": "application/vnd.sun.wadl+xml",
                              "rel": "describedby"
                          },
                          {
                            "href": "http://docs.openstack.org/api/openstack-compute/2/wadl/os-compute-2.wadl",
                            "type": "application/vnd.sun.wadl+xml",
                            "rel": "describedby"
                          }
                      ]
                  }
              }

Yes I do.

      responses:
        200:
          description: A High School
          schema:
            $ref: "#/definitions/HighSchool"
          examples:
            application/json: |-
              {
                "SchoolName": "Blah",
              }

The json version is just the 'exported json' version of the yaml from Swagger UI

smccormick
Participant I

ok, I think we have tracked down our current problem...there currently is a bug with rendering example JSON strings defined in OpenAPI/Swagger spec yaml files. If you remove those example strings, you will get the spec to render with the default example documentation for your objects (see attached screen shot). We will work on a fix for this to support example JSON objects in the spec (not sure on the turn around time), but removing these example blocks will get you working in the meantime.

specremoveexamples.png

Yup, that was it.

Thanks,