Swagger-ui: SEO and google-ability of dynamic generation

[erikvanzijst]

As we're evaluating swagger-ui for our public-facing API documentation, I wonder if its dynamic approach of downloading swagger.json and constructing the page at runtime will prevent the documentation from getting crawled and becoming searchable.

According to Google:

To make the crawler see what a user sees, the server needs to give a crawler an HTML snapshot, the result of executing the JavaScript on your page.

https://developers.google.com/webmasters/ajax-crawling/docs/learn-more

Is there anything I'm overlooking here, or could this really be an issue?

[fehguy]

While google is getting better at rendering & indexing dynamic content, I'm not sure if swagger-ui is indexable. I do seem to find quite a few swagger-ui instances via google search, but haven't spent a bunch of time figuring out what is being indexed on them.

[erikvanzijst]

Google is getting better, but it does not currently run javascript to the point of making ajax calls, as indicated by their docs.

We're evaluating swagger-ui as a candidate for Bitbucket's future API documentation. However, searchability of the documentation is key to making our API accessible.

To verify, I got Google to index our swagger site, which confirmed that it merely looks at the index.html and never pulls down the swagger.json:

Are there plans to make swagger-ui indexable, or providing a way to generate static HTML offline?

[dolmen]

Related: swagger-api/swagger-editor#664

[erikvanzijst]

So after learning about the spec attribute to SwaggerUi(), I can confirm that using that over the AJAX-based URL approach fixes the crawling problem.

I embedded the swagger json data in a .js file:

$ ( echo -n 'var spec = ' && curl http://url.to/swagger.json ) > swagger.js

then loaded that synchronously in the page's head:

<script src='/swagger.js' type='text/javascript'></script>

fed it to SwaggerUi():

window.swaggerUi = new SwaggerUi({
  url: null,
  spec: spec,
  ...

And Google now indexes correctly:

[webron]

@erikvanzijst - thanks for sharing the details of your research. I'm sure it would prove helpful to other users.

[imZack]

wow, very useful hack. it's better to add in docs.
thanks for sharing.